Skip to main content

General API Topics

Authentication​

The following authentication measures are used for Merchant or Distributor Backend -> Zastrpay Backend API calls:

API Key​

An API Key in x-api-key header is used for authenticating direct calls from the Merchant or Distributor Backend to the Zastrpay Backend.

curl -0 -v -k -X POST https://host.com/path \
   -H "x-api-key: $apiKey"

Please contact Zastrpay Support for getting an API key.

Source IP Restriction​

Source IP Restriction is configured for the Zastrpay endpoints in question.

Please contact Zastrpay Support for having your IP whitelisted.

Retries and Idempotency​

Every PUT/PATCH/POST request to Zastrpay Backend API should contain a x-request-id header with a new clientside-generated UUID/GUID value. Every genuinly new request should have a new UUID/GUID value generated. In case of retry the same x-request-id value should be used as for the initial request.

For example, the client wants to call PUT https://host.com/resource1/{resourceId}, then a new UUID/GUID should be generated and passed in the x-request-id: {requestId1} header.

If the operation is not successful due to for example timeout, and the client is not sure whether this request was actually processed by the server or not, then it should simply retry the same PUT https://host.com/resource1/{resourceId} call with the same x-request-id: {requestId1} header value. The server will recognize this is a retry by the x-request-id header value, and will not perform the operation twice, in case it performed it already the first time and simply the response did not reach the client on the way back.

Throttling​

The requests to Zastrpay Backend API are throttled down in case more than X requests per second are sent from a single source IP address. Please contact Zastrpay Support for further information.

HTTP Requests, HTTP Verbs​

Request payload is in JSON format.

In the majority of cases Zastrpay APIs use PUT + client-generated resource id (UUID/GUID) for creating new resources (instead of POST + server-generated resource id).

POST is used whenever a specific action is exercised on an existing resource, e.g. POST .../some-resource/{resourceId}/cancel, POST .../some-resource/{resourceId}/approve, etc.

HTTP Responses, Errors​

Standard HTTP Status Codes are used for all responses. Response payload is in JSON format.

Successful responses have http status code 2xx and rarely 3xx. The payload of such responses contains usually the attributes of the resource that has been created/modified or simply retrieved.

note

Responses to PUT and POST requests include all resource attributes in the payload (instead of empty response and Location header only).

Usually the following success response codes are used:

  • 201 Created - for PUT requests
  • 200 OK - for POST requests or GET requests
  • 303 - exceptionally used for PUT requests where the to-be-newly-created resource is actually merged to an already existing one

Error responses have http status code 4xx in case of client/validation error, or 5xx in case of server error.

Usually the following error response codes are used:

  • 400 Bad Request - the request could not be validated, or some consistency/business constraint known to the client could be satisfied
  • 401 Unauthorized - the request could not be authenticated (e.g. invalid API key). Could originate from the infrastructure and contain a non-standard error payload (see below)
  • 403 Forbidden - the (already authenticated) caller does not have the permission to invoke this operation. Could originate from the infrastructure and contain a non-standard error payload (see below)
  • 404 Not Found - the resource could not be found (e.g. invalid resource id)
  • 409 Conflict - the caller tries to modify a resource which was modified by another caller or system process in the meantime. The caller should retrieve the resource and retry the modification.
  • 422 Unprocessable Entity - some consistency/business constraint known to the client could be satisfied upon performing th operation
  • 429 Too Many Requests - client has issued too many requests. Originates from the infrastructure and contains a non-standard error payload (see below)
  • 500 Internal Server Error - unexpected failure condition occurred while processing the request (could be a programming bug, or infrastructure issue). Could originate from the infrastructure and contain a non-standard error payload (see below)
  • 503 Service Unavailable - usually infrastructure issue, and may contain a non-standard error payload (see below)

The standard error payload looks like this:

{
  "code": "Validation",
  "message": "The field \"customerId\" could not be validated.",
  "correlationId": "ce8056cd-ae4d-4f2d-87de-7562c92f92cc",
  "details": {
    // optional strongly-typed attributes giving more information about the error code which can be used programmatically
    "validationErrorReasons": [
      {
        "fieldName": "customerId",
        "errorMessage": "Value must not be empty"
      }
    ],
    "mergedToCustomerId": "40c7fe9f-3bf9-464a-8d3a-937db20f5dae"
  }
}

API Versioning​

Zastrpay APIs follow semantic versioning in the format MAJOR.MINOR.PATCH. MAJOR is never or very rarely changed, as all changes introduced to the APIs are backwards-compatible. MINOR is usually incremented when backwards-compatible changes are made to Zastrpay APIs.

Backward-compatible changes include:

  • new API endpoints, new operations to existing endpoints
  • additional optional request query or payload attributes
  • additional response payload attributes
  • additional enum values
warning

Usually x-extensible-enum is used instead of normal enum to "motivate" the client to treat these as string and gracefully handle new values added later on.

Zastrpay is currently not using x-extensible-enum due to documentation/code-generation issues with it, however clients must treat enums as strings or x-extensible enums in their code, and be able to accommodate for new values added to the enums later on!