Skip to main content
Version: 1.0

Transport layer (HTTP)

The transport layers main role, is to connect the client with the underlying RPC API. In order to reach the API, we are relaying on plain HTTP POST requests, where the RPC request is embedded within the body. However, in order to reach the API, there are also a few other things that needs to be in order. First of all, we need to be able to authenticate the the integration. We do this by checking the Authorization header, to see that it contains either valid basic auth credentials, or a valid OAuth 2.0 access token. Secondly, we need to know that the integration body contains JSON; if not, there is no reason to connect it to a JSON RPC API. Thirdly, we need to connect it to an API version that match what the integration was actually written for. We do this by checking the X-API-Version header.

HTTP Headers

The following HTTP request headers are expected by the Clarify API.

Authorization"<type> <base64 encoded content>"YesOAuth2 Access Token grating access to Clarify.
Content-Type"application/json"YesMIME type used to encode the request body. Must always be "application/json".
X-API-Version"1.0"NoSelect which API version to use. If omitted, the latest stable version is used.

HTTP Response Status Codes

JSON RPC 2.0 and Status codes

Note that unlike e.g. REST APIs, JSON RPC 2,0 does not use HTTP status codes for errors. This is because JSON RPC is transfer protocol agnostic. Always check the error in the response body when retrieving a 2xx status code.

A non 2xx status code will be returned if the transport of the RPC request to the the target API, or the transport of the response back to the client failed to complete.

Status codeDescription
200 OKSuccessful transport of RPC request (when the JSON RPC "id" filed was set).
204 No ContentSuccessful transport of RPC notification request (when the JSON RPC "id" filed was not set).
5xx Server Errors5xx codes indicates that the API either could not be reached or did not respond as expected.
401 UnauthorizedInvalid, missing or expired API credentials.
400 Bad RequestTransport to API not possible with current headers. E.g. X-API-Version not found or invalid Content-Type etc.