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 developing such tools, or for understanding how calls are validated or rate limited 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.
The transport protocol layer
In principal, there could be multiple transport protocols for an RPC API, but for now, we only support HTTP. The transport layer has four main roles:
- Authenticate the client.
- Enforce rate-limiting to ensure fair-share access among multiple consumers.
- Facilitate Version selection.
- Bring the client in connection with the RPC protocol layer.
If failing to connect to the API for any reason, we will get a non 2xx status-code.
The RPC protocol layer
Clarify uses JSON RPC 2.0 as a remote procedure call (RPC) protocol. Using this protocol we define a set of methods that your integration code can call with a correct set of parameters. The exact set of method and allowed parameters, depend on version selection. Methods are organized in namespaces, which we use for limiting API access.
Doing a JSON RPC request against Clarify, is less complicated than it might sound. All you need to do is to make a POST request against https://api.clarify.io/v1/rpc with the right headers and a valid JSON RPC request body. When able to reach the API, you get either a 200 OK HTTP response with a valid JSON RPC response in the body, or a 204 (No Content) with an empty body for notify requests.