Each API travels through the API lifecycle, where it goes through the different stages of release, updates, and eventually deprecation.
API versioning
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.
API launch stages
eBay has three stages of release for APIs and developer products: Alpha, Beta, and General Availability (GA). In addition to release stages, an API can also have Experimental releases. Experimental is not a release phase in the same sense as Alpha, Beta, and GA; it does not represent a maturity model and can occur at any of the three release stages. This table summarizes the purpose and usage of each type of release:
| Characteristic | 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 |
| Intended use: | 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 |
Limited Release APIs
Some eBay RESTful public APIs or specific API methods are not available to all developers. These capabilities are designated as Limited Release. eBay restricts access to these APIs and methods to developers/applications that provide the most value to eBay, eBay buyers and sellers, and the eBay developer community. Access to Limited Release APIs is contingent upon invitation from eBay and/or a rigorous business case review and signed contracts.
Note: Limited Release is not a release phase, such as Beta or GA, which implies API maturity. However, the release phases apply to Limited Release APIs. That is, a Limited Release API may be in any release phase, such as Experimental or GA.
As with all of the RESTful public APIs, access is controlled through scopes. Once an application has been approved to use a Limited Release API, the required scopes will be made available, allowing access tokens to be generated with the necessary permissions.
Refer to the documentation of the API to learn if or how you can get access.
Experimental APIs
The purpose of eBay’s experimental APIs is testing and research. eBay uses experimental releases to test new business capabilities or features and analyze impact. Experimental APIs are not tied to release phases and eBay has no commitment to refine or deliver to full maturity (i.e., GA release). Experimental may apply to a complete API, an individual resource, or a method. An experimental resource or method can be added to (or removed from) an API at any of the three launch phases.
Important! Experimental does not imply low quality, lack of support, or poor performance. Experimental is not a release phase, such as Beta or GA, which implies API maturity. However, changes to an experimental API may not be backward compatible and can occur at any time. API or interfaces may be removed with little notice. Use at your own risk. Experimental APIs are suitable for limited production use, but not for business critical use.
Experimental API access could be subject to eligibility criteria. Refer to the API documentation for more information.
eBay deprecation policy
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. The API endpoints will continue to be available during the deprecation period. The deprecation details are documented on the API deprecation status page.