Consider how to simplify usage of DELETE

[garethsb]

Follow-up to #22.

With the 409 Conflict response we need to determine if there's a way all the conflicting resources could be indicated (we use a single resource Location header in this situation in IS-04 Registration API).

A few choices:

1. Discover all of the Network Flows that refer to the Endpoint, via a query to /network-flows?sender_endpoint_id={endpointId} and/or /network-flows?receiver_endpoint_ids={endpointId} depending on the Endpoint role. DELETE those flows first, then DELETE the endpoint.

   👍 Reasonably efficient (1 + N + 1 requests)
   👎 Relies on support for query parameters in the Network Control API

2. Attempt to DELETE the endpoint. Get a 409 Conflict with a Location header (or define a new response header) indicating one (all) conflicting Network Flow (Flows). DELETE that flow (those flows). Repeat until you stop getting 409 Conflict.

   👍 Doesn't rely on query params being supported
   👎 Inefficient (1 + 2 * N requests)

3. Attempt to DELETE the endpoint. Get a 409 Conflict with a new response header ('Locations') indicating all conflicting Network Flows. DELETE those flows. DELETE the endpoint.

   👍 Doesn't rely on query params being supported
   👍 Reasonably efficient (1 + N + 1 requests)

4. Support DELETE with a query string, so you can make a smaller number of requests:
   DELETE /network-flows?sender_endpoint_id={endpointId}
   DELETE /network-flows?receiver_endpoint_ids={endpointId}
   DELETE /endpoint/{endpointId}

   If we adopted RQL, it'd only need two requests:
   ?query.rql=or(eq(sender_endpoint_id,{endpointId}),eq(receiver_endpoint_ids,{endpointId})

   👍 Most efficient (3 - or 2 - requests)
   👎 Support for query params on DELETE is a new invention (for NMOS APIs at least)

[garethsb]

2. Attempt to DELETE the endpoint. Get a 409 Conflict with a Location header (or define a new response header) indicating one (all) conflicting Network Flow (Flows).

The Location header is most commonly used in responses to creation requests (especially POST where the newly created resource will have a new unique URL) and in redirect responses (301, 307, etc.). We adopted it in IS-04 to indicate the location of the conflicting resource in a 409 Conflict response.

However, as discussed, it doesn't allow a list of URLs to be returned. Interestingly there is a note in RFC 7231 Section 6.4.1 for the 300 Multiple Choices response, that explains that Location should be used for the preferred redirection, but others may be indicated using the Link header using a relation of "alternate". Using Link (which is a list header) would work equally well for us here. We could define a new relation of "conflict" if we liked.

Request

DELETE /endpoints/{endpointId} HTTP/1.1

Response

HTTP/1.1 409 Conflict
Location: /network-flow/{networkFlowId-1}
Link: </network-flow/{networkFlowId-1}>;rel="conflict", </network-flow/{networkFlowId-2}>;rel="conflict",</network-flow/{networkFlowId-3}>;rel="conflict"