API life cycle and deprecation strategy
To keep you up to date with the latest versions of APIs, Pismo must occasionally deprecate and decommission older versions of APIs. When an endpoint or API is deprecated, Pismo strongly recommends updating to the newest versions before the decommission date. This allows for a smooth upgrade path to a newer release.
Terms and concepts
|API and Endpoint||Each product on the Pismo platform has a speciﬁc API, providing many services, known as endpoints. A Pismo API provides at least one endpoint. Endpoints represent the services that can be executed by an API product.|
Every endpoint belongs to a speciﬁc API. For example:
|Deprecation||A service has been ended (with or without a new version becoming available). Support for the older API is limited to bug fixes only.|
|Sunsetting||Period of time from the deprecation date to formal decommissioning. The sunsetting period is usually six months. However, endpoints presenting vulnerability issues are decommissioned within three months.|
|Decommissioning||Older version is no longer available. Requests sent to this version fail beginning on the decommission date.|
API life cycle
|Version Status||Description||Documentation||Support||Pismo Bulletin|
|Active||Most up-to-date and recommended API version||Available on launch date.||Fully supported. Update with bug fixes and new features.||Notifications published two weeks prior to launch and again on launch date.|
|Deprecated||API is planned for removal and may or may not be superseded by a newer version.|
New customers or new integrations by existing customers are denied access to deprecated APIs.
|The version is marked as Deprecated on the day of deprecation.||Supported for six months from the deprecation date (bug fixes only).||Notification published on deprecation date.|
|Decommissioned||API is longer available. The version is decommissioned six months after in the deprecated status.||No documentation provided.||No support provided.||Notifications published 90, 60, 30, 15, and 7 days prior to decommissioning and again on the decommissioning date.|
|Deprecation date||Pismo Bulletin and Changelog|
|90, 60, 30, 15, and 7 days before decommissioning||Pismo Bulletin|
|Decommission date||Pismo Bulletin and Changelog|
The URL for an endpoint includes an element specifying the version of the API it uses. For example, in the URL
https://api-sandbox.pismolabs.io/events/v1/timeline, the v1 element indicates that it uses version 1 of the API for that endpoint. For more information about endpoint structure, see Environments.
Your API version controls what parameters you can send in requests and which ones you receive in the responses. So, if you’re using an older version of an API, you should upgrade to the latest version to take advantage of new functionality or improved processing. To see if there are any new API versions available, check out the Pismo Changelog and the latest version of the documentation.
Legacy versus latest APIs
In exceptional cases, Pismo may maintain a legacy API alongside an upgraded one. In these cases, you should use the latest API version for all new development, to avoid rework when the legacy API eventually is deprecated.
Backward compatible changes
Backward compatible changes in your version are available automatically. These changes typically introduce new features or improve performance, do not disrupt your current implementation. To use a newer version, you shouldn't have to do anything to keep things working correctly.
Pismo considers the following changes to be backward compatible.
- Adding API resources.
- Adding optional request parameters to existing API methods.
- Adding properties to existing API responses.
Updated 2 months ago