Requests to Services

From Ocean Framework Documentation Wiki
Jump to: navigation, search

HTTP Headers

Required

The following header should be present in all requests to Ocean services.

Accept: application/json

You must include the following header if the request is a POST or PUT request with a body. You may include it in calls using other methods too, but it's required only when there's a body.

Content-Type: application/json

Optional

Ocean accepts three special headers:

HTTP Header Usage
X-API-Authenticate For ApiUser authentication. Cf. Authentication and Authorisation.
X-API-Token For authorisation of API requests. Cf. Authentication and Authorisation.
X-Metadata Used to create an audit trail for Ocean requests. The value of this header is recorded in the system-wide aggregated Ocean log together with the request and response. Thus, by passing in something like a customer id, a shopping cart id, or a transaction number, all requests belonging to that ID can easily be traced. The value must be a string no longer than 128 characters. NB: The X-Metadata header will be passed on in any subsequent requests the service makes as a result of the original request, including any asynchronous jobs executing at a later time.

Cache-Control

You're free to use any Cache-Control options in your requests to the Ocean API.

You should know, however, that must-revalidate, no-cache, and no-store in incoming requests will be filtered away. One of the main reasons for this is that allowing requests forcibly to reach the backend servers is a Denial of Service attack vector.

This doesn't mean that you can't use must-revalidate, no-cache, and no-store, please do: they are useful to control intermediate caches.

But as the Ocean architecture is an aggressive caching architecture, the Ocean cache can always be trusted to contain up-to-date and accurate information. Thus there is no need to force a backend server hit, and the Cache-Control options which force this can be filtered away.

For in-depth information about caching in Ocean:

Query Args

Hygiene-aware clients should take care to sort all query args in alpha order on the keys, or make sure they always appear in the same order in the URI, otherwise the backend servers may be hit unnecessarily. For instance,

GET /v1/things?foo=1&bar=2

and

GET /v1/things?bar=2&foo=1

are cached separately as the result of two separate backend server requests.

If you do all your HTTP requests to Ocean using an abstraction layer, you might want to sort query args there. Otherwise just make sure the order of your query args is consistent in your client app code.

HTTP Body

The body, when present, should always be well-formed JSON.

Old Browsers from Hell

Old, substandard web browsers such as IE6 may not offer very great flexibility in specifying HTTP headers. Therefore, for such clients, the Content-Type will always default to application/json and UTF-8.

Ocean has built-in support for transforming query args in ancient browsers:

?_method=xxxxx
will use xxxxx as the HTTP method (use POST as the base method to avoid caching).
?_x-api-authenticate=xxxxx
is transformed into an X-API-Authenticate HTTP header.
?_x-api-token=xxxxx
is transformed into an X-API-Token HTTP header.
?_x-metadata=xxxxx
is transformed into an X-Metadata HTTP header.

These query args can be combined and mixed with other query args using &, as usual.

Bottle.jpg NOTE: Transformation is not performed for modern browser clients; you must always use the proper HTTP methods if you have access to them. The above query args are only for obsolete and deeply hated "browsers" such as Internet Exploder and other horrible vestiges of a terrible and dark past still lingering on in the dark recesses of completely out-of-touch enterprises.