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	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	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 Path issues	Optional	Map of request parameter issues by path. Omitted if empty.

Error codes

JSON RPC standard error codes:

Code	Name	Description
-32700	Parse error	Invalid JSON was received by the server.
-32600	Invalid request	The JSON sent is not a valid Request object.
-32601	Method not found	Method does not exist / is not available.
-32602	Invalid params	Invalid method parameter(s).
-32603	Internal error	Internal JSON-RPC error.
-32000 - -32099	Server error	Reserved for implementation-defined server-errors.

Clarify specific error codes:

Code	Name	Description
-32000	Server error	Fallback error code when the server is not able to set a more specific code.
-32001	Produce invalid resources	Produce invalid resource(s) in Clarify.
-32002	Found invalid resources	Found invalid resource(s) in Clarify.
-32003	Forbidden	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	Conflict	The operation is not allowed because it causes a conflict with existing resource(s) in Clarify. Could be caused by unique field constraints on resources or concurrent write operations.
-32011	Too many requests	Access to a specific RPC method has been blocked due to rate-limit constraints; reduce the call-rate of the client to stay within the documented rate-limit. Consider sequential instead of concurrent requests.
-32015	Try again	Indicates an availability issue; the client should consider to try the request again after a delay.
-32021	Partial failure	Returned when an operation could only partially be performed.
-32023	Too many items selected	Returned by clarify.evaluate when too many items are selected.