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.

For a current list of deprecated endpoints, see Deprecation schedule.

Terms and concepts

TermDefinition
API and endpointEach product on the Pismo platform has a specific 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 specific API. For example:
  • Products: Accounts API, Cards API
  • Endpoints: Get account status, Create a card
DeprecationA service has been ended (with or without a replacement becoming available). Support for this service is limited to bug fixes only.
SunsettingPeriod of time from the deprecation date to decommissioning. The sunsetting period is usually six months. However, endpoints presenting vulnerability issues are decommissioned within three months.
DecommissioningOlder version is no longer available. Requests sent to this version fail beginning on the decommissioning date.

API life cycle

Version StatusDescriptionDocumentationSupportPismo Bulletin
ActiveMost up-to-date and recommended API versionAvailable on launch date.Fully supported. Update with bug fixes and new features.Notifications published two weeks prior to launch and again on launch date.
DeprecatedAPI is scheduled for decommissioning 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.
DecommissionedAPI is no 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.

Communication schedule

ScheduleCommunication method
Deprecation datePismo Bulletin and Changelog
90, 60, 30, 15, and 7 days before decommissioningPismo Bulletin
Decommission datePismo Bulletin and Changelog

API upgrades

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.

📘

Outdated APIs

In exceptional cases, Pismo may maintain an outdated API alongside a current one. In these cases, you should use the latest API version for all new development. This will help to avoid rework when the outdated 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, but 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