The Clarify API is using JSON RPC 2.0 as the API communication protocol. RPC stands for Remote Procedure Calls, and works very much like how you would call a function within a programming language: you call a named function with a set of input parameters, and may expect the return of a result. In JSON RPC though, we call them methods and not functions.
To call an RPC method in Clarify, you simply make a HTTP POST request with a JSON formatted body containing a single RPC Request. All requests are made against the exact same URL endpoint
https://api.clarify.io/v1/rpc. For how to authenticate against the API see Authentication.
In addition to absolute requirements, we align with most of the recommendations from the specification that could make writing a client easier. This includes allowing both named and positional parameters as well as sticking with recommendations for error formatting. We also allow the client to decide on the type to use for the id field.
However, we have chosen not to support JSON RPC batch requests for the time being. This is because we don't think there is a need for it with our current API design.
"id" field in the request is omitted or set to
null, the server will assume the client is not intending to wait for a response, and we won't return one. The JSON RPC spec calls this a "notification".
It's up to your client to decide on the data type and value to use for the ID field, as long as it's a valid JSON value. The same ID that is used in the request will be used in the response. However, if your client doesn't have any specific needs, we recommend that you just use
1 as it's a short and simple value. This is the value that is typically used by our SDKs.
|Version of JSON RPC protocol to use. Must be |
|A client side request ID. Set to any value except |
|Name of method to invoke.|
|Input parameters for the method, encoded either as positional parameters (array) or named parameters (object). We offer better backwards-compatibility for named parameters.|
"method": "<RPC METHOD>",
You will only get a JSON RPC response when you are able to reach the API. You will not be able to reach the API if you either select a non-existing version, your client fail to authenticate, or your client is rate-limited. In such cases, you will receive a transport layer error. If you are able to reach the API, but didn't set a request ID, then you will also not receive a JSON RPC response.
The JSON RPC 2.0 specification does not allow both
error to be present in the response. The Clarify API defines that a
result, when present, is always an object. The error, when present, follow our own Error schema.
|Will always be |
|The client-side ID used for the request.|
|The result of a successful method call, present on success.|
|The result of a failed RPC method, present on error.|
"message": "Invalid params",
Error describe the standardized JSON RPC 2.0 error format, as well as a Clarify specific data field and error codes. When an error is present, the result portion will be empty.
|Yes||A code describing the error type.|
|Yes||A textual description of the error.|
|No||An object describing more details related to the error. The structure of the ErrorData object is Clarify specific.|
Error data is a Clarify specific format for embedding useful error information.
|Always||A unique ID that can be supplied to the Clarify Support team to help us debug what happened for a particular failed request.|
|Optional||Map of request parameter issues by path. Omitted if empty.|
Below is a list of the possible values for the
code field. Codes written with a bold font are specific to Clarify, while the other codes are defined by the JSON RPC 2.0 specification.
|-32700||ErrParseInvalidJSON||Indicates invalid JSON is received by the server.|
|-32600||ErrInvalidRequest||Indicates the sent JSON is not a valid Request object.|
|-32601||ErrMethodNotFound||Indicates the method does not exist / is not available.|
|-32602||ErrInvalidParams||Indicates invalid method parameter(s).|
|-32603||ErrInternal||Indicates an internal JSON-RPC error.|
|-32000||ErrServer||Indicates a generic server error.|
|-32001||ErrProduceInvalidResources||Produce invalid resource(s) in Clarify.|
|-32002||ErrFoundInvalidResource||Found invalid resource(s) or code issue in Clarify.|
|-32003||ErrForbidden||Indicates that the requested operation is not permitted by your current access token, or that the input parameters are referencing a resource that isn't accessible / doesn't exist.|
|-32009||ErrConflict||Indicates a conflicts with current state of Clarify resource(s).|
|-32015||TryAgain||Indicates that the response should be called again later. Maybe returned in the case of temporal errors or rate limited requests.|