Skip to main content
Version: 1.0

API reference

When working with the Clarify API, you often don't work with it directly. You probably work with it through an SDK (Software Development Kit) in a programming language such as Python or Go. This documentation is for the Clarify API, which is the underlying service that these tools talk to. Knowledge of this layer is important for deveoping such tools, or for understanding how calls are validated or rate limted in this layer. We will include examples from the different SDKs in the doc so that you can more easily understand how the API calls relate to to the SDK that you are using.

Integration CodeClarify SDK (pyclarify, clarify-go etc.)HTTP (Transport layer)JSON RPC 2.0 (API layer)Clarify API

The Transport Layer​

In princiapal, there could be multiple transport layers for an RPC API, but for now, we only support HTTP. The transport layers has three main roles:

  1. Allow communication between the integration code and the server. We do this by allowing a JSON RPC response to be embedded in a HTTP POST request body.
  2. Authenticate the client to verify that the integration is who it says it is. We do this by checking the content of the Authorization header.
  3. Version selection in order to match the integration with the API version it was written for. We do this by checking the conteint of the X-API-Verision header.

You can read more about each of this secitons in the sections that follows.

The API Layer​

The Clarify API uses HTTP as the transport layer for JSON RPC 2.0. More specifically, it relies on POST requests against https://api.clarify.io/v1/rpc. For a request to be valid, it must include the headers defined in this sections, as well as a valid RPC Request in the body.

For the response, clients should also decide on how they want to handle status codes returned by the transport layer. Only when the status code is 200, will there be an RPC Response available in the response body.