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
ascashback
within thepromotions
block.
1.4.3 - Update currency
display in get-card
response
- Returns a standard
currency
object across allcampaign
types withinget-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
andadd-basket
- Update parameters to allow multiple parallel wallets
- Previous name of
basket_vouchers
array in response JSON ofget-vouchers
changed tovouchers
.
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 namesadd-basket
endpoint request and response JSON updated to change parameter nameslock-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.