The Symmetrical API lifecycle consists of 4 stages: Prototype, Active, Deprecated, Removed.
- Prototype - can change at any time (including breaking changes), with or without a notice.
- Active - live endpoint with ongoing support for fixes and new features; generally, no breaking changes - however when breaking change occurs, this is planned to give sufficient time for adjustment
- Deprecated - not actively maintained or updated (including for new features)
- Removed - deprecation period ended and API is no longer in Production
All APIs that are not in Active stage will be marked accordingly in documentation.
Prototyping policy
We shall introduce and open for use an early phase API endpoint(s) or new parameters.
All API endpoints in this phase shall be marked as ‘prototype’ in documentation.
APIs in ‘prototype’ stage can be changed at any time with 15 days notice (or less in agreement with Launch customers), including breaking changes.
API in prototype stage can be throttled or removed altogether at any time.
We shall provide a mechanism for customers to share feedback on early stage APIs.
Active policy
The majority of our endpoints will be in an Active state. Active state means you can use and rely on those endpoints.
Active API’s shall be enhanced with new functionality, which you can start using at your own convenience. Functional improvements shall not constitute a breaking change and we shall ensure that the enhancements can be used on an opt-in basis.
For Active APIs, all improvements will be communicated to you via Release Notes on at least a weekly basis.
We shall have the option to introduce a “Breaking Change” on Active API endpoints - deprecating particular fields or making some fields mandatory. For this type of change, we shall follow the Deprecation Policy.
Deprecation policy
If we intend to introduce a breaking change - remove features or enforce new mandatory rules - we shall provide at least 3 months notice.
We shall clearly indicate upfront which APIs or which API functions shall be deprecated. We shall use a standard Change Guide (explained below) for communicating these changes to customers.
If available, we shall provide a new API to use instead of the deprecated API.
We shall strive to make our APIs backward-compatible. Whenever possible, we shall use the API expand-contract approach. If an API isn’t backward-compatible, it’s your responsibility to transition to the new API within the deprecation window.
To ease transition, we shall provide a Migration Playbook and shall be ready to answer your support requests through our Service Desk.
We shall initiate three types of API deprecation:
Deprecating functions - endpoint remains the same, but one or more fields change
Deprecating a complete endpoint - the whole endpoint is deprecated
Deprecating a set of endpoints or a full product - multiple endpoints (or parts of endpoints) are deprecated
Other (than deprecation) API usage changes shall be applied that constitute a Breaking Change for customers:
Introduction of additional recommended or mandatory parameters - for mandatory parameters introduction same policy applies as for deprecation.
Request throttling - we retain the right to throttle requests to preserve system stability. Any throttling introduction is subject to 30 days notice. For misbehaving clients, we might enforce mandatory parameters or throttling at any time (subject to client notification and appropriate remediation).
If an API creates a verified security risk, changes are required by legislation or imposed by a third-party relationship (including changes in law or relationships), we may provide less than 3 months notice before making changes or removing APIs.