Occasionally Spaaza makes changes to the payload sent to or response received from an API endpoint. This may include adding new request or response fields. 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.
It should be noted that Spaaza’s approach is generally that we may add optional request fields, or fields to response JSON, without a version change, but that we will only remove fields, or change their type or name, in a new API version, and that that change should avoid affecting API clients consuming endpoints with existing versions.
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.
- Switch default behaviour of
get-campaignsAPI endpoint. Previously, inactive campaigns would be included in the API response by default unless the
exclude_inactiveparameter was set to
true. Now, inactive campaigns are excluded by default unless
exclude_inactiveis set to
- Update gender field in
userobject to support male, female, nonbinary, transgender, agender, genderqueer, genderfluid, bigender, twospirit, androgynous, pangender, neutrois, demigender and other.
- New structure for
purchase_progressarray in response to
- Additions of
vouchers_createdarray in response to
- Update the
item_pricerequest field to change definition item price net of vouchers and other Spaaza rewards to be redeemed.
- Add the
item_original_pricerequest field to send the original gross per-unit price of a basket item before Spaaza vouchers and rewards.
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.