After working with improperly versioned SOAP-based APIs for many years, eBay decided to move to new RESTful APIs with semantic versioning and a deprecation standard. Focus is on extensibility and adaptability to make it easier for developers to create new applications that utilize eBay’s APIs. In a blog post, Tanya Vlahovic describes the concepts and how they are implemented in their APIs.
For Vlahovic, lead public API architect at eBay, APIs represent the business, but she emphasizes that individual APIs are not enough; they must be used together to bring real value to the business. She compares eBays’ set of APIs with cooking — the APIs are the ingredients and it’s then up to the developer community to come up with a great meal by combining different APIs in some new and innovative way.
To create an API ecosystem that is flexible and adaptable, it is important to understand if individual APIs are a success or a failure; are they used by developers or just ignored? Vlahovic believes that API owners should be very open and look for solutions from different perspectives when trying to improve the APIs and get them used. Two examples of new APIs that she thinks have changed how people think are search by image and machine text translations, both released last summer.
Vlahovic describes an API as doing three simple things: it performs actions and gathers data, it formats data, and finally it serves the data. She believes that the easiest way to create an API is to design intuitive and straightforward contracts without spending a lot of time on documentation, and then let developers try it out and assess its value. She points out that APIs are interfaces for human developers, not for robots.
In their new RESTful APIs, they follow semantic versioning with three quality levels: alpha, beta and general availability. Beyond these levels, they also support experimental APIs. This allows for early adopters to explore, test and give fast feedback on the APIs.
Their deprecation standard focuses on both the contract and runtime behaviour, and applies to the same quality levels they use in versioning. When they deprecate an element in an API, for example a resource, a field or behaviour, the elements are normally maintained in their original form for 18 months. For every new deprecation of an element, a new minor version of the API is released, and it's accompanied by a public announcement with detailed instructions to developers. If needed, the instructions also include migration instructions. If a deprecation causes a backward incompatibility, the API owner must decide if instead of a minor version, a new major version is released.
Whenever an element is deprecated, the deprecated attribute is added to the element, and the description attribute is updated to reflect the deprecation. Both attributes are defined in the OpenAPI specification. At runtime they inform about a deprecation using a standard Warning HTTP response header with the code 299. This header should be logged and monitored by consumer applications so that developers can be alerted about new changes.
Vlahovic sees APIs as building blocks that enable developers to create new applications. To simplify this work, eBay provides SDKs that abstract away some concepts. One example is the industry standard OAuth 2.0 protocol that is used by eBay to handle authorization and data privacy concerns. They require that all API clients are authorized before they use their marketplace capabilities, and support for this is therefore included in the SDKs. In addition to the existing open source Java OAuth client library, they recently released a C# and a Python version of the library.
In an earlier blog post, Vlahovic wrote about eBay’s two year journey to deliver a new family of APIs for their marketplace and what they learned during that time.
