Link Search Menu Expand Document

Versioning

Introduction

Occasionally Spaaza makes changes to the payload sent to or response received from an API endpoint. In order to maintain backwards compatibility with existing API clients a versioning policy is put in place. The aim of this policy is to make using endpoint features as simple as possible.

Usually a Spaaza API endpoint maintains backward compatibility without requiring special flags, but in the case that a specific version is required, the API documentation for that endpoint will show clearly what is needed. If there is no information about versioning in the documentation for a specific endpoint, then there is no need to do anything. Spaaza recommends sending an appropriate version header with all API requests.

Occasionally version-specific changes become available in the Spaaza API which affect multiple, or all, endpoints. This kind of change is described in the section API-wide version information below. Again, this kind of change is designed to be non-breaking and as backwards-compatible as possible.

Using a specific endpoint version

With certain Spaaza API endpoints specific versions are implemented. In order to the latest version of an API endpoint, a version header is sent along with the request to the API endpoint. The documentation for a specific endpoint will always contain information about which version number should be used.

The following header is used for specifying a version:

  • X-Spaaza-API-version:

Spaaza uses standard semantic numeric major.minor.fix version numbering, for example:

  • X-Spaaza-API-version: 1.4.3

API-wide version information

This section includes information about version-specific changes which affect multiple, or all, endpoints in the Spaaza API. In the case that these changes affect all endpoints, for example a change in the way error responses are handled between different versions, a description of the change is not usually included in the documentation for any specific individual endpoints.

A description of each of this kind of version-specific change is shown below.

1.4.4 - Update get-card display for cashback campaigns.

  • Returns Campaigns of type cashback as cashback within the promotions block.

1.4.3 - Update currency display in get-card response

  • Returns a standard currency object across all campaign types within get-card promotions block.

1.4.2 - Allow float values for basket item quantities

  • Allow float values for basket (line) item quantities in get-basket-price and add-basket
  • Update parameters to allow multiple parallel wallets
  • Previous name of basket_vouchers array in response JSON of get-vouchers changed to vouchers.

1.4.1 - Remove URL format requirements

  • Remove requirement for .json or .php suffixes at the end of API endpoint URLs
  • Remove requirement for v1/ in API endpoint URLs

1.4.0 - Updates to formatting of JSON error responses

  • Error responses for all API endpoints updated to reflect semantic correction of errors -> error where only a single error is returned.

API clients using a version number less than 1.4.0 will receive the previous error formatting in the JSON returned in the error response. Documentation for older clients is available on request.

1.1.8 - Updates to formatting of JSON in get-basket-price and add-basket endpoints.

  • get-basket-price endpoint request and response JSON updated to change parameter names
  • add-basket endpoint request and response JSON updated to change parameter names
  • lock-voucher endpoint parameters and response JSON updated to change parameter names

API clients using the above endpoints should use a version number greater than or equal to 1.1.8. Documentation for older clients is available on request.