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.
With most Spaaza API endpoints version-specific differences are implemented. In order to use 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 if there are changes differences that are specific to that endpoint.
There are also version-specific differences that apply to all endpoints, such as how errors are formatted in API responses. These are detailed in the ‘API-wide version information’ section below.
The following header is used for specifying a version:
X-Spaaza-API-Version: <version number>
Spaaza uses standard semantic numeric major.minor.fix version numbering, for example:
NOTE that if no
X-Spaaza-API-Version header is supplied then a version number of
1.0.0 is assumed.
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.
birthdaydate format in
user_inforesponse object to
add-basketresponse to include
item_original_pricein request object for basket item and to display
voucher_distribution_estimatedwarning for requests that include on the fly basket campaign vouchers, but the item_original_price is missing from all the basket items.
get-cardresponse to return
get-user-entity-cardwhen API client version < 1.4.5
- Returns Campaigns of
- Returns a standard
currencyobject across all
- Allow float values for basket (line) item quantities in
- Update parameters to allow multiple parallel wallets
- Previous name of
basket_vouchersarray in response JSON of
- Remove requirement for .json or .php suffixes at the end of API endpoint URLs
- Remove requirement for
v1/in API endpoint URLs
- Error responses for all API endpoints updated to reflect semantic correction of
errorwhere 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.
get-basket-priceendpoint request and response JSON updated to change parameter names
add-basketendpoint request and response JSON updated to change parameter names
lock-voucherendpoint 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.