APIs represent business and enable it to expand into new contexts and experiences. The entire API portfolio is what brings value to organizations. Individual APIs are not sufficient to allow developers to be innovative. The APIs are powerful when used together, so the portfolio dimension is what matters. Combined, our APIs give access to valuable eBay marketplace capabilities. There are great analogies between cooking and integrating with APIs. We believe that we provide healthy ingredients. It is up to our developer community to be inventive and come up with great recipes to delight their customers.
Developer ecosystem
“Precisely one of the most gratifying results of intellectual evolution is the continuous opening up of new and greater prospects.” - Nikola Tesla
The easiest way to do APIs is to design intuitive and straightforward contracts. APIs are interfaces for people. They are for human developers. (There is intelligence beyond artificial that still matters.) The goal is to integrate with APIs without spending too much time on documentation or filing developer technical support tickets. An API is like a joke. Need for a further explanation typically indicates unnecessary complexity.
In general, APIs do three simple things. (I am going to skip here all of the technical challenges that are sometimes behind the steps below.)
- Perform actions and gather data
- Format data
- Serve data
It takes time to assess the value of an API; to understand whether releasing an API was a success or a failure. It is essential to embrace change and emphasize an API ecosystem that is flexible and adaptable. If all you have is a hammer, then every problem looks like a nail. When it is challenging to meet developers’ needs, the API owners should change the perspective and look for a different solution to improve the API portfolio. Typically, there are many ways to solve the problem. Building a developer ecosystem is hard, with so many technical (and other) challenges, but if done well, it expands in the right direction.
In the commerce world, disruptive forces are powerful these days. Augmented and virtual reality and artificial intelligence, with speech and image recognition, and all sort of self-learning systems, are everywhere. These innovations have the power to dramatically reshape the buying and selling experience and transform the way people interact with the digital world. At eBay, we are exposing such capabilities through APIs. Search by image and machine text translations released last summer is just the beginning.
On the other side, sometimes API capabilities disappear for various reasons: business policy or strategy changes, not meeting business objectives, challenging to integrate with. So, there was a need also to standardize this aspect of the API lifecycle.
API deprecation standard
At eBay, we have specifications for both API versioning and deprecation. Versioning is a controversial topic among developers. It is one of the most common debates in the API world. After dealing with improperly versioned SOAP-based APIs for 10+ years, we decided to change the approach with our new modern RESTful APIs. We follow semantic versioning and have alpha, beta, and general availability quality levels defined. Also, we support experimental APIs. The purpose of such capabilities is exploring, testing, and getting feedback from our API early adopters and partners.
Our API deprecation standard is focused on both the API contract and runtime behavior. The deprecation specification applies to all API quality levels: alpha, beta, and general availability as well as experimental capabilities. Deprecating an API version, or entire API is the final stage of the API lifecycle. It is the best option when the API does not meet business goals. Some of the reasons for the API deprecation are:
- Business policy or strategy change
- Experimental capability/API no longer serves a business objective
- Inefficiency
- Low usage
Elements of the API that could be deprecated are:
- Resource/method
- Field
- Enumerated value
- Query parameter
- HTTP header
- Behavior
- API (major) version
- Entire API across all major versions
Deprecated API elements are maintained in their original form for 18 months. Exceptions to this policy are possible and apply in case of critical business decisions. A transparent public announcement accompanies deprecation of any API element. It contains detailed instructions to developers, including migration plans if applicable. The API deprecation announcement is published on our Developer Portal and may include other communication channels.
In some cases, deprecated elements cause backward incompatible changes. It is on the API product owners to decide on the approach: proceeding with deprecation or releasing a new major version.
We use the deprecated attribute from the OpenAPI specification to declare deprecated API elements: methods, fields, query parameters, and headers. Also, we change the OpenAPI specification description attribute to reflect the deprecation. The following example is for the deprecating actualDeliveryDate field.
ShippingFulfillment:
type: "object"
properties:
actualDeliveryDate:
type: "string"
description: "This field has been deprecated. For instructions on how to migrate to the new version, visit eBay Developer Portal. The date the purchase order was delivered."
deprecated: true
For any new deprecated API element, we release a new minor API version. Such a release requires an API documentation update, and it includes the new API contract and proper communication to developers.
HTTP response header to convey deprecation
In runtime, we leverage a standard Warning HTTP response header with the 299 code to reflect deprecated API elements. The purpose of the Warning header is to be logged and monitored by developers. According to the HTTP Protocol specification, 299 code (Miscellaneous Persistent Warning) is not a dedicated code for deprecation. To simplify the consumption of this information on the client side, we use the 299 code for deprecated API elements only. In case of any API deprecation, the Warning HTTP header is present in every single applicable response irrespective of the HTTP status code.
When a method, a query parameter, or an HTTP header is deprecated, the Warning header is part of every response coming from a deprecated method or a method having query parameter or HTTP header deprecated. In case of a deprecated field, enumerated value, or behavior, responses from all of the methods where these elements are used or relevant have a Warning header specified. When an API major version is deprecated, every method’s response includes a Warning header. In case of an entire API deprecation, this applies to all of the API major versions.
API clients should log the HTTP deprecation header and have proper alerts and monitoring in place. Instructions and examples are documented on the eBay Developer Portal as part of Best Practices for Integration with eBay RESTful Public APIs.
Syntax
Warning: <warn-code> <warn-agent> <warn-text> [<warn-date>]
<warn-code>
A three-digit warning number. It is always 299 (Miscellaneous Persistent Warning) to reflect the deprecated API element(s). 299 code here is not HTTP response status code; it is just part of the Warning header content.
<warn-agent>
The warn-agent value is API hostname. Examples: api.ebay.com, api.sandbox.ebay.com
<warn-text>
The Warning header includes the warning text, which contains brief information about the deprecation. The warning text has a link to public API documentation explaining the deprecation. The warning text is intended to be presented to a human user or logged.
<warn-date>
The Warning header includes the deprecation date. The format is the same as HTTP Date header as defined by RFC 7231 Date/Time Formats.
Cardinality
Multiple warnings, with the same 299 code and different warning text, may be generated in response. This is to reflect multiple API elements to be deprecated at different point of time.
Examples
Return policy fields restockingFee and extendedHolidayReturnsOffered are deprecated in Account API. Below Warning HTTP header is present in all methods defined for return_policy resource.
Warning: 299 api.ebay.com "Deprecated return policy fields: restockingFee and extendedHolidayReturnsOffered. We will keep supporting them for the next 18 months. For more information, visit https://developer.ebay.com/api-docs/sell/account/deprecation.html" “Wed, 15 Jun 2018 00:00:00 GMT”
Version 1 of the Account API is deprecated. Below Warning HTTP header is present in all methods under version 1 of Account API.
Warning: 299 api.ebay.com "You are using a deprecated version of the API. We will keep supporting it for the next 18 months. For instructions on how to migrate to the new version, visit https://developer.ebay.com/api-docs/sell/account/deprecation.html" “Wed, 15 Jun 2018 00:00:00 GMT”
We considered standard Sunset HTTP header to convey the fact of API deprecation to clients but discarded that idea due to the following reasons:
- The Sunset response header is still in draft.
- The Sunset response header indicates the upcoming retirement of a resource or an API. It is not ideal for deprecation of other API elements: fields, enumerated values, and behavior.
- There is no support for multiple Sunset headers to communicate multiple deprecations happening at a different time. The Sunset response header contains a single timestamp when a resource is expected to become unresponsive.
We are also following this year’s efforts to introduce (and standardize) a Deprecation HTTP response header to signal the API deprecation to clients.
SDKs
“We are what we repeatedly do. Excellence, then, is not an act, but a habit.” - Aristotle
APIs are intermediaries that enable applications to interact. They are building blocks for developers to innovate and create their products. On the other side, SDKs are tools that simplify working with building blocks by abstracting some of the concepts like various cross-cutting concerns. SDKs enable developers to create new applications or new building blocks.
This year, we continue with open-sourcing tools for APIs. We recently released C# and Python OAuth client libraries that simplify integration with our APIs. This is in addition to previously open-sourced Java OAuth client library. For proper authorization and to address data privacy concerns, we leverage the industry-standard OAuth 2.0 protocol. All eBay APIs require clients to be authorized to use our marketplace capabilities. When leveraging our libraries, a few lines of code are sufficient for the integration with eBay OAuth services.
Feed API exposes the greatest selection of inventory to our partners. This includes new, everyday items as well as rare goods — if something exists in the world, it is most likely for sale on eBay. Partners use our data feeds to create a rich selection of items and enable their users to find their version of perfect. Feed SDKs abstract downloads and large file manipulation and simplify typically complex inventory curation. They allow authorized partners around the globe to programmatically access the vast selection of eBay items and curate the inventory of their choice to fit their business models. After last year’s Java Feed SDK, we recently released the Python client.
At eBay Connect last summer, we announced that OpenAPI documents are available for our RESTful APIs. We demonstrated that integration with read-only capabilities takes a few minutes. Our libraries simplify this further. Instead of delivering black boxes, we open-sourced SDKs to provide full transparency to developers into what is happening in their integrations. (And we welcome contributions from the developer community!)
The road ahead
Our API gold rush continues. We have passionate teams with a common goal: to craft APIs engineers love and to deliver a world-class developer experience that enables partners to innovate. We are announcing improvements and additions to our API portfolio next week at eBay Connect. Stay tuned!
References
Wikipedia contributors. (2019, May 15). Law of the instrument. In Wikipedia, The Free Encyclopedia. Retrieved 05:47, May 25, 2019, from https://en.wikipedia.org/w/index.php?title=Law_of_the_instrument&oldid=897198823.