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.
13. As per ReST API standards, the resources are accessible by path parameters that identify the resource using the Eclipse identifer for the resource. In simpler terms, API's are often of the form ../customers/{customerId} e.g. /customers/123 would refer to customer 123. 123 is assigned by Eclipse when a new customer is created. The same applies to tenants, wallets and organisations. In the case of customers, wallets and organisations, they can be created on Eclipse passing an externalUniqueId which is a String that globally uniquely identifies that resource. E.g. for a customer it could be the SIF of the customer in a banking system. To simplify API access, one can use "EUID-{externalUniqueId}" to identify a resource instead of using the Eclipse assigned identifier. Eclipse will then transparently replace the "EUID-{externalUniqueId}" in the path with the Eclipse assigned ID prior to processing the request. E.g. /customers/EUID-ABC would be changed to /customers/123 if ABC is the externalUniqueId of the customer 123. This pattern can be used for any {walletId}, {organisationId} or {customerId} in the Eclipse API's. For wallet specifically, accountNumber can also uniquely identify a wallet and to use account number in the path, one can use /wallets/ACC-{accountNumber}