The transport layer defines how link transitions made at the document layer are mapped to network requests.
When effecting a link transition, an appropriate transport should be selected based on the scheme portion of the URL.
Core API currently defines a single HTTP transport.
The HTTP transport
The HTTP transport supports the
Link transitions for this transport are effected via an HTTP request/response, as determined below.
Determining the request method
The request method is determined based on the link
- The link
actionshould be uppercased to give the resulting HTTP method.
- When no link
actionis specified, the default method is
Encoding link parameters
Link parameters are encoded into the request in different ways, depending on the parameter
location="path"- The parameter is included in the URL, using URL templating.
location="query"- The parameter is included in the URL, as a query parameter.
location="form"- The parameter is included in request body.
When no parameter location is specified, the default is to use
location="form" for all other actions.
Because path and query parameters can only handle string encodings a simple mapping of the parameter values is required.
- String values are encoded as-is.
- Integer and Number values are encoded as their equivalent string representation.
falsevalues SHOULD be encoded as the literal strings
nullvalue SHOULD be encoded as the empty string,
- Array and Object parameter values are not supported and their usage SHOULD raise an error.
If form parameters are included, then the parameters are treated as a mapping of key-value pairs.
The resulting map MUST be
JSON encoded. The encoded parameters MUST then be included in the request body and the
Content-Type header of the request SHOULD be set to
Determining the request headers
Requests are free to include any standard HTTP request headers, in particular:
- An appropriate
Acceptheader MAY be included in the request, indicating the encodings that the client supports.
- Clients MAY choose to include additional headers to support authentication, request signing, or other use cases.
Decoding the response
The result of following a link transition is to either return a Document, or raise an Error condition.
- The resulting content is decoded by selecting an available codec based on the response
- Either a Document or an Error condition MUST be returned by the codec.
- If no content is present in the response then the transport layer MUST return an empty document.
Handling in-place transformations
An in-place transformation takes place when a link has
transform="inplace", and the
link is contained by a nested document.
transform property is the empty string, an appropriate default is used:
DELETEmethods default to
- All other methods default to
In the case of an in-place transformation, a partial transformation is effected on the document tree, as follows:
- If a Document is returned in the HTTP response: The nested document is replaced with the returned Document, and the new document tree is returned to the client.
- If no content is returned in HTTP response: The nested document is removed from the document tree, and the new document tree is returned to the client.
Coercing 4xx and 5xx responses to errors
When a 4xx or 5xx response is received the transport layer SHOULD coerce any Document returned into an Error. This allows media types that do not support an error primitive to be handled gracefully.
When a 4xx or 5xx response is received that contains a media type that is
not a supported hypermedia format, the transport MAY attempt to use fallback
media types to decode the content and return an Error. For example, a transport
MAY support graceful handling of error responses that have been returned in