General Guidelines

1. The API’s are ReSTful and available over TLS using HTTP/1.0, HTTP/1.1 and HTTP/2

2. Message bodies are JSON

3. API’s are physically hosted in Ireland so network latency from Africa is about 180ms

4. Other than some of the ratify API’s that can take a number of seconds, most API’s have a latency of <100ms (excluding network latency)

5. All API requests are audited and tracked to the user and IP address. Attempts to circumvent the system security, send inappropriate load, or perform fraudulent activities will be tracked down and dealt with to the full extent of the law. If API users discover vulnerabilities or are able to exploit the system then please report as such to [email protected].

6. Most API's that return a list of results can be passed query parameters offset and limit. The offset is a 0 based index of which result to return from. Defaults to 0. The limit is the number of results to return and typically defaults to 1000. These can be used for pagination when required but most often the defaults are fine.

7. APIs use HTTP response codes as follows:

• 404 : The resource could not be found. (e.g. a request for a specific customer, wallet etc was not found in the database).
• 400 : Bad input data in a query parameter or body found. E.g. a parameter was invalid or incorrect in the context of the request.
• 401: Bad authentication credentials or JWT
• 403: Insufficient permissions for the caller to do what they are trying to do
• 500 : Something unexpected went wrong while processing the request. This would typically be a system-level error and is likely to work if re-tried later.
• 204 : With no response, body means the resource was created successfully or the operation completed successfully.
• 200 : Success with a response.

In addition to the HTTP error code, errors return with a body with a list of errors (normally only one). Refer to the section on Application Error Codes for details.

Example:

[
  {
    "code": "USR007",
    "description": "Incorrect code",
    "severity": "LOW",
    "type": "BUSINESS",
    “traceId”: “hchuewhuiehdiwhei”
  }
]

9. The error type can be BUSINESS or SYSTEM. SYSTEM indicates a system error and may work if retried later. BUSINESS indicates a validation error or user error. Errors will normally include a traceId which can be quoted if reporting an error so that it can easily be traced by Eclipse operations support.

10. All API’s perform initial data validation against the published schema on Swagger. Validation failures are reported as BUSINESS errors with error code VAL001. E.g.:

[
  {
    "type": "BUSINESS",
    "severity": "LOW",
    "description": "Value '' for NewEclipseTenant's companyNumber is invalid: It must be a minimum of 5 and maximum of 20",
    "code": "VAL001"
  },
  {
    "type": "BUSINESS",
    "severity": "LOW",
    "description": "Value '' for NewEclipseTenant's apiKey is invalid: It must be a minimum of 36 and maximum of 36",
    "code": "VAL001"
  },
  {
    "type": "BUSINESS",
    "severity": "LOW",
    "description": "Value 'string' for NewEclipseTenant's phone1 is invalid: It must be a minimum of 10 and maximum of 20",
    "code": "VAL001"
  }
]

11. The swagger contains detailed schema descriptions and field requirements. Click on the schema tab to see these:

12. In order to avoid dirty writes, many API's include a version field for a record. This must be populated with the same version as is in the database or else one will get an error "The data being updated has already been updated by something else. Open the record again and make your changes and save". The normal pattern to follow when updating a record is to GET the current record, make applicable updates and then PUT with the updates. This prevents two clients from making changes and overwriting each others updates.