Versioning and the API lifecycle
Each API travels through the API lifecycle, where it goes through the different stages of release, updates, and eventually deprecation.
The eBay RESTful APIs have three part version numbers, where each part is separated by periods ("."). For example, version 1.0.0 designates the first release of an API, and later releases of the API will update one or more of the version-number parts. Despite the similarity to decimal points, any or all three of the version-number parts can be greater than 9. For example, 1.12.47 is a valid version number.
The three version-number parts are defined as the major.minor.maintenance versions of a release, where each version-number part represents a different type of change in the API. With this, you can interpret an API at Version 1.3.7 as being at major version 1, minor version 3, and maintenance version 7.
To illustrate how you should handle new versions of an API, the following list outlines a series of updates that start with Version 1.3.7:
- Version 1.3.8 increments the third version number. This is a maintenance release of backwards-compatible bug fixes, or similar updates, that were applied to the previous version (Version 1.3.7).
- This change should have no effect on you other than noticing that the version has been updated. You do not need to make any changes to your code.
- Version 1.4.0 increments the minor release number. This represents new, backwards-compatible functionality applied to Version 1.3.8.
- The API now has additional response fields, new optional parameters, new commands, or something similar. You can continue using the API with your existing code, but you should update it to make use of the API's new aspects.
- Version 2.0.0 is a major release. The major release number is incremented, and the other version numbers are zeroed out. Major version releases include backwards-incompatible API changes from the previous release of the API.
- The API has deprecated a method, added a new required parameter, etc. You should update your code, including your API call URIs, so it works with the new version. However, you can continue to use the old version with no code changes, at least for a while (see below for eBay's version deprecation policies).
- Major version changes require a change in the URIs you use to make calls to that API; as discussed in REST operation URIs, the URI in the operation includes the API's major version number.
APIs return their full three-part version number in all responses via the
X-EBAY-C-VERSION HTTP response header.
eBay has three stages of release for APIs and developer products; Alpha, Beta, and General Availability (GA). This table summarizes the purpose and usage of the different stages:
|Launch Stage||Alpha||Beta||General Availability (GA)|
|Purpose and benefit||Purpose is to test and develop API features and functionality requirements. Opportunity to preview and influence future eBay API features.||Purpose is to release API capabilities for feedback. Opportunity to get early access to new APIs before GA.||Purpose is to release API features for production use.|
|Who can access||Available to select eBay Developers Program Members with NDA.||Available to all eBay Developers Program Members, may be subject to eligibility criteria.||Available to all eBay Developers Program Members, may be subject to eligibility criteria.|
|What support is provided||Support is provided by account management support only, and may not have formal documentation||Standard technical support channel available, with draft documentation.||Standard technical support, with full documentation available.|
|API design stability||Changes to API likely from feedback in Alpha testing, and Beta may not be backward compatible with Alpha.||Changes to API possible during Beta period and GA may not be backward compatible with Beta.||Stable Interface Design|
|Quality||May have significant design and availability issues.||May have design and availability issues.||Production|
|Suitable for:||Test environments or limited-use testing.||Limited production use but not for business critical use.||Production|
|Usable for customer onboarding?||No||Yes||Yes|
|Usable for load testing?||No||No||Yes|
Although eBay strives to make updates to its APIs compatible with all previous versions, there are times when an API becomes outdated and eBay must deprecate the API in order to provide a better service to its customers.
eBay guarantees support for deprecated major versions of an API for at least 6 months, and will usually support deprecated APIs for up to 18 months. API deprecation takes place when there is a major version change (for example, from Version 1.4.0 to Version 2.0.0). In these cases, you can still send requests to a deprecated major version for 6 months (and possibly longer), but you should update your client to handle the new version as soon as feasible.
Within an API, if a deprecated item still allows for backwards compatibility, it causes a minor version increment (for example, from Version 2.4.56 to Version 2.5.0). If a deprecated item causes backwards incompatibility, it causes a major version increment (e.g., from 2.4.56 to 3.0.0).
Remember, a major version change means you have to change your calls in your applications so they address the API's new endpoint. Normally this entails changing the major version number component of the URI. For example, the URL of an operation might change from the first listed to the second: