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
The following HTTP request headers are expected by the Clarify API.
|Yes||OAuth2 Access Token grating access to Clarify.|
|Yes||MIME type used to encode the request body. Must always be |
|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.
|Successful transport of RPC request (when the JSON RPC |
|Successful transport of RPC notification request (when the JSON RPC |
|5xx codes indicates that the API either could not be reached or did not respond as expected.|
|Invalid, missing or expired API credentials.|
|Transport to API not possible with current headers. E.g. |