General Guidelines

1. API Overview

• All APIs are RESTful and accessible over TLS.
• Supported HTTP versions: 1.0, 1.1, 2.
• Message format: JSON.

2. Hosting and Latency

• APIs are hosted in Ireland.
• Typical network latency from Africa: ~180ms.
• Most API requests respond within 100ms (excluding network latency).
  Certain endpoints, such as Ratify APIs, may take several seconds.

3. Auditing and Security

• All API requests are audited and tracked by user and IP address.
• Attempts to bypass security, overload the system, or commit fraud will be investigated and prosecuted.
• If you discover a vulnerability or exploit, please report it to [email protected].

4. List APIs: Pagination

• APIs that return lists support query parameters:
  • offset – zero-based index of the first result to return (default: 0)
  • limit – number of results to return (default: 1000)
• Use these parameters for pagination if needed, though defaults are usually sufficient.

5. HTTP Response Codes

• Errors also return a body with one or more error objects. See Application Error Codes.

Example Error Response

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

• Error types:
  • SYSTEM – system-level errors; may succeed if retried
  • BUSINESS – validation or user errors
• Most errors include a traceId for reference.

6. Data Validation

• APIs validate input against the published Swagger schema.
• Validation failures are returned as BUSINESS errors with code VAL001.

Example Validation Response

[
  {
    "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"
  }
]

• Detailed schema descriptions and field requirements are available in the OpenAPI reference:

7. Preventing Dirty Writes

• Many APIs include a version field for records.
• The version must match the current database value; otherwise, the request fails:

"The data being updated has already been updated by something else. Open the record again, make your changes, and save."

• Recommended update pattern:
  1. GET the current record
  2. Apply updates
  3. PUT the updated record

8. Resource Identification

Resource access: Use path parameters with Eclipse-assigned IDs.

• Example: /customers/{customerId} → /customers/123

• Works for tenants, wallets, and organisations too.

External unique IDs: Optionally create resources with a globally unique string (externalUniqueId).

• Example: a customer’s CIF in a banking system.
• Path: /customers/EUID-{externalUniqueId}
• Eclipse replaces EUID-{externalUniqueId} with the internal ID automatically.
• Example: /customers/EUID-ABC → /customers/123
• Supported IDs: {paymentId}, {cardId}, {walletId}, {organisationId}, {customerId}

Wallets by account number: You can also reference wallets by accountNumber.

• Path: /wallets/ACC-{accountNumber}