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.
| Name | Content | Required | Description |
|---|---|---|---|
Authorization | "<type> <base64 encoded content>" | Yes | OAuth2 Access Token grating access to Clarify. |
Content-Type | "application/json" | Yes | MIME type used to encode the request body. Must always be "application/json". |
X-API-Version | "1.0" | No | Select which API version to use. If omitted, the latest stable version is used. |
HTTP Response 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 code | Description |
|---|---|
200 OK | Successful transport of RPC request (when the JSON RPC "id" filed was set). |
204 No Content | Successful transport of RPC notification request (when the JSON RPC "id" filed was not set). |
5xx Server Errors | 5xx codes indicates that the API either could not be reached or did not respond as expected. |
401 Unauthorized | Invalid, missing or expired API credentials. |
400 Bad Request | Transport to API not possible with current headers. E.g. X-API-Version not found or invalid Content-Type etc. |