Your API version controls the API behavior you see (e.g., what properties you see in responses, what parameters you’re permitted to send in requests, etc.). Your version gets set the first time you make an API request. When we change the API in a backwards-incompatible way, we release a new dated version, but to avoid breaking your code, we don’t change your version until you’re ready to upgrade.
PlusAuth considers the following changes to be backwards-compatible:
- Adding new API resources.
- Adding new optional request parameters to existing API methods.
- Adding new properties to existing API responses.
- Changing the order of properties in existing API responses.
- Changing the length or format of object IDs or other opaque strings.
This includes adding or removing fixed prefixes (such as
ch_on charge IDs).
You can safely assume object IDs we generate will never exceed 255 characters, but you should be able to handle IDs of up to that length. If for example you’re using MySQL, you should store IDs in a
VARCHAR(255) COLLATE utf8_bincolumn (the
COLLATEconfiguration ensures case-sensitivity in lookups).
- Adding new event types.
If you’re running an older version of the API, upgrade to the latest version to take advantage of new functionality or to streamline responses, so the API is faster for you. Upgrading your API version will affect:
- The API calls you make without a
PlusAuth-Versionheader: the parameters you can send, and the structure of objects returned.
- The structure of objects received from REST API and PlusAuth libraries.
- The structure of objects sent to your REST API endpoints.
See the API changelog for details about how your default API version will impact these operations.
To see what version you’re running and upgrade to the latest one, visit your Dashboard.
When performing an API upgrade, make sure that you specify the API version that you’re integrating against in your code instead of relying on your account’s default API version. To test a newer version for API calls, set the
PlusAuth-Version header (in live or test mode).
For 72 hours after you’ve upgraded your API version, you can safely roll back to the version you were upgrading from in your Dashboard.
We send information on new additions and changes to PlusAuth’s API and language libraries in the PlusAuth Developer Digest. Be sure to subscribe to stay informed.
The changelog is a list of backwards-incompatible updates in the API. As described above, new additions and forward-compatible changes don’t need a new API version and will not appear in this list.