Our web services consist of a collection of HTTP RESTful(ish) APIs utilizing JSON format, servers are listening on the following hosts offering secure TLS connections.
| Host | Environment | Description |
|---|---|---|
| rest.prod.rafiki-api.com | Production | This is the actual live environment, It should only be utilized once your integration has been thoroughly tested in the sandbox environment. |
| rest.sandbox.rafiki-api.com | Sandbox | You can use this environment to safely test your integration code |
Request
Requests employ standard HTTP methods, also known as verbs, including POST, GET, PUT, and DELETE, as outlined in RFC 7231, unless a specific endpoint specifies otherwise.
Every resource detailed in this document provides instructions on the required request structure, encompassing HTTP body, headers, and other essential components.
As a general guideline, any POST or PUT request that includes a body requires the appropriate Content-Type header, indicating the associated MIME serialization strategy (currently supporting only JSON). Without this header, our server will promptly reject the request, responding with an HTTP 400 error.
Response
Each response body will be serialized according to the high level structures outlined below :
HTTP 2xx
Property Type Description "data" array/object Employed to precisely depict the response data of resources. If a single entity is returned, the data is represented as an object. Conversely, when multiple records need to be listed, the data structure becomes anarray."meta" object Relevant metadata unique to the resource, such as pagination information and total record count.
HTTP >= 4xx
Property Type Description "code" enum Specific error message categorisation (See error codes) "message" string A human-readable description explaining the reason for the request failure. "errors" object An object containing key/value pairs to provide a detailed and granular representation of the failure reason.
Status codes
Status codes play a pivotal role in crafting a polished HTTP API design. Irrespective of the architectural approach, responses must consistently align with the semantics of the selected status code.
While the HTTP standard already defines the meaning of each code, this particular section of our documentation aims to provide further clarity on their utilization within the context.
| Status | Description |
|---|---|
| 200 | This indicates a generic “success”, the server has successfully interpreted the request, executed its job, and responded back accordingly. |
| 201 | Successful requests in a create context. E.g. a brand new record was inserted. |
| 202 | Upon receiving the request, the server successfully acknowledges and accepts it. However, the actual execution of the work is deferred as it is pushed into a queue. The resource typically provides a dedicated endpoint for polling job update statuses. It is your responsibility to make periodic requests at specified intervals to check for updates. |
| 400 | The server couldn't process the request accurately. This could be due to issues such as a malformed JSON object or a missing/mismatched Content-Type header. |
| 401 | When attempting to access a protected resource with an API key that is invalid, expired, or blacklisted |
| 402 | When trying to transfer money from a wallet that lacks the required balance. |
| 403 | When the API key is valid but lacks the necessary permissions to access the resource, or is explicitly prohibited from performing the specified action. |
| 404 | The requested resource at the provided URL cannot be found, or any referenced ID within an HTTP request body does not exist. |
| 409 | When two or more requests are concurrently using the same idempotency key. |
| 422 | Similarly with the 400 status code, the difference here lies in the reason for the error. In this case, the error is due to a validation issue. Although the JSON document's structure is syntactically correct, one or more of its properties may be invalid concerning the specific resource. For instance, it could be a phone number that doesn't adhere to the specified format. |
| 500 | An issue occurred on our end. We will have logged the request to identify the root cause and resolve the problem. |