Proposal for 201 Created responses

[octomad]

Hyperion spec makes no mention of what type of response a 201 should be sending back. In order to reach some type consistency across all Hyperion compliant APIs there should be a standard in place for this.

According to the HTTP spec:

... a Location header field in the response or, if no Location field is received, by the effective request URI. The 201 response payload typically describes and links to the resource(s) created

According to Mozilla's dev site

The HTTP 201 Created success status response code indicates that the request has succeeded and ... the new resource is returned in the body of the message, its location being either the URL of the request, or the content of the Location header.

Both of those references have similarities but also some differences -- most notably the mention of what the body/payload should include. We should lean towards what former HTTP spec mentions however it does leave some room for interpretation using words like "typically describes" and not a MUST. The Location header is common and should be part of the headers.

Given this, I see three possible avenues that an API can take. Return a Location header along with:

1. No response body - not terribly useful
2. Full / partial resource returned - most clients don't use the resource returned here. In edge cases where a client needs the new resource, then can go back and GET it. This saves the API server (and developers) from having to re-query the state from the data store.
3. Hyperion LinkValue to the new resource - While redundant with the HTTP specification, this appears to be the most Hyperion-esque. Not only do APIs benefit from not having to re-query, the response provides useful information about where the new resource is located.

An example header + payload response for option 3 could be:

HTTP/1.1 201 Created
Date: Sun, 10 Nov 2021 23:26:07 GMT
Server: AWSGW Server...
Location: https://api.sample.com/apis/3d3f9275-a2bc-4fcc-be7b-a229f1d85ed3/specs/6e17e006-eddb-4c24-9618-94ad5d28c9b4

{
    "@type": "NodeRef",
    "@links" : {
        "location": {
            "href": "/apis/3d3f9275-a2bc-4fcc-be7b-a229f1d85ed3/specs/6e17e006-eddb-4c24-9618-94ad5d28c9b4",
            "description": "A reference to the new API Specification"
        }
    }
}

[teehill]

Personally I vote to keep our convention of @id

[octomad]

the problem that i had with @id is that it represents the current document being returned. In this case, it isn't referring to the current doc but rather a ref to the resource that was created.

[teehill]

@id isn't solely for representing the current resource, it's used as a reference in other places (like Collections). It's our version of hypertext navigation.