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 http: and https: schemes.

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 action property.

Link parameters are encoded into the request in different ways, depending on the parameter location property.

When no parameter location is specified, the default is to use location="query" for GET and DELETE actions, and location="form" for all other actions.

Encoding path and query parameters.

Because path and query parameters can only handle string encodings a simple mapping of the parameter values is required.

Encoding form parameters.

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 application/json.

Determining the request headers

Requests are free to include any standard HTTP request headers, in particular:

Decoding the response

The result of following a link transition is to either return a Document, or raise an Error condition.

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.

When the transform property is the empty string, an appropriate default is used:

In the case of an in-place transformation, a partial transformation is effected on the document tree, as follows:

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 plain application/json and/or text/html formats.