API protocol (JSON RPC)

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.

Alignment with JSON RPC 2.0 specification

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.

Request

Set the "id" field

If the "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.

type: object

Field	Description
jsonrpc string("2.0")	Version of JSON RPC protocol to use. Must be "2.0".
id any	A client side request ID. Set to any value except null to request a response; the response will contain the same ID as the request.
method string	Name of method to invoke.
params array, object	Input parameters for the method, encoded either as positional parameters (array) or named parameters (object). We offer better backwards-compatibility for named parameters.

Example

request

{
  "jsonrpc": "2.0",
  "method": "<RPC METHOD>",
  "id": 1,
  "params": {}
}

Response

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 result and 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.

type: object

Name	Description
jsonrpc string("2.0")	Will always be "2.0".
id any	The client-side ID used for the request.
result object	The result of a successful method call, present on success.
error Error	The result of a failed RPC method, present on error.

Examples

Response with result

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {...}
}

Response with error

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "trace": "00000000000000000000",
      "params": {
        "integration": ["required"]
      }
    }
  }
}

Error

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.

type: object

Name	Type	Require	Description
code	integer	Yes	A code describing the error type.
message	string	Yes	A textual description of the error.
data	Error data	No	An object describing more details related to the error. The structure of the ErrorData object is Clarify specific.

Error data

Error data is a Clarify specific format for embedding useful error information.

type: object

Name	Type	Presence	Description
trace	string	Always	A unique ID that can be supplied to the Clarify Support team to help us debug what happened for a particular failed request.
params	map of string => array of string	Optional	Present when the error code and message can be traced back to specified parameters.

Error codes

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.

Code	Name	Description
-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.