An API — or application programming interface — is an intermediary that enables applications to interact. It is a contract that specifies how applications talk to one another. Further, an API creates a separation between a service provider and its consumers. Essentially, it decouples their implementations. As long as the contract stays intact, API providers may continue changing their code and underlying dependencies without destabilizing clients.
APIs are a big deal. After dealing with SOAP-based legacy APIs for years, eBay started a journey to deliver a new, modern family of APIs for sellers and buyers. Our principal goal was to design a set of interfaces that will meet business objectives, attract developers, replace our legacy APIs, and be long-lived. This is not an easy job. As I mentioned, APIs are a contract, and as such, they cannot be changed in ways that break existing integrations. APIs should evolve and grow with the business, so they must also be expandable and flexible. Now, that is hard.
Our challenge was to create a vision for the API, plan ahead and design a stable contract that will last for years, even as we add business capabilities. Here is how we did it.
Governance
“Ensuring and validating that assets and artifacts within the architecture are acting as expected and maintaining a certain level of quality.” — Gartner
To achieve consistency across the APIs, we followed a governance process and compliance model. One of our most important goals was improving the quality of the APIs by defining and enforcing standards and policies. We established a governance process that was objective, transparent, manageable, and explicit. Our compliance model for web services is platform- and tenant-agnostic and fits well into eBay’s overall API maturity model. Levels of compliance are specified by a set of characteristics and capabilities that may be measured and assessed. This helps to identify and quantify a realistic target maturity for our APIs in a given period. (And, it is testable!)
Design and beyond
“Unfortunately, people are fairly good at short-term design, and usually awful at long-term design.” — Roy Fielding
First and foremost, the API blueprint is the starting point. At eBay, a blueprint describes detailed API design enough to verify, implement, maintain, and extend capabilities in the future. Designing APIs has many analogies to building a house. Without a proper blueprint, pressure to deliver on time often leads to a poor design. To further frame an analogy to house construction, working without a blueprint causes shortcuts similar to building a bathroom in the kitchen since the plumbing work has already been done there. The challenge lies in finding a balance between our agile product development methodology and time needed to come up with a detailed design. Implementation becomes straightforward once there is a blueprint and clear understanding of what needs to be done.
For our new family of APIs, we followed our interface design method (“IDM”). The IDM is the process of arriving at an underlying model and a stable contract. It starts with capturing use cases by specifying actors, concepts, and actions, and then deriving entity relationships. Further, nouns are identified from the entities and verbs from the actions. The final phase of the IDM process is determining resource representation and specifying authorization details.
Use cases
| Actor | Use case | Description | Constraints |
|---|---|---|---|
| Seller | Seller creates an advertising campaign | The seller creates an advertising campaign and specifies a name, effective dates, funding strategy, and a criterion that defines inventory partitioning. | The advertising campaign is either a rule-based campaign, where listings are auto-selected according to specified inventory partitioning criteria or a campaign with listings added by reference. A listing belongs to only one effective campaign.
The currently supported funding model is the cost per sale (CPS). Inventory is partitioned based on following dimensions:
|
| . . . |
Entity relationships diagram
Methods
| HTTP request | Authorization (OAuth 2.0 scope) |
|---|---|
POST /sell/marketing/v1/ad_campaign |
https://api.ebay.com/oauth/api_scope/sell.marketing |
| . . . |
We followed pragmatic RESTful principles with standard implementations around cross-cutting concerns: error handling, security, behavioral tracking, and operational metrics. APIs represent the consumer’s view of the capabilities, and the URI names must be meaningful to developers. Our URI pattern takes a consumer-centric approach by providing a consistent, predictable, and understandable names across APIs. This pattern makes an API intuitive and easy to discover and consume. In most of the cases, the new APIs use JSON for resource representations. It is compact and easy to parse and translate. For certain use cases, supporting additional formats is straightforward, since our RESTful architecture style leaves room for such flexibility. So far, we have managed to stick to standard formats and media types. OAuth 2.0 protocol is leveraged to address security and data privacy concerns. Here, the challenge was to balance the need of fine-grained scopes that protect data and activities while managing the scope policies.
APIs are more than pure design and implementation. They include documentation, technical support, terms of use, and various operational aspects. Bringing transparency to the process through frequent discussions between architects, product owners, and engineering teams was crucial. Getting feedback from technical writers helped to achieve vocabulary consistency across APIs. For sure, all of the teams were aligned on what the success is: to build APIs that developers will love and want to use.
The road ahead
We delivered modern RESTful APIs that cover a subset of our overall marketplace capabilities and follow industry standards, well-established patterns, and best practices. Still, they are powered by a model that is flexible and extensible enough to capture new opportunities that might come in the future. Our journey is not yet complete. We are engaging customers, listening to feedback, and encouraging adoption of the new APIs, all to bring our new, long-term public API program to reality. Our goal is a large and powerful ecosystem of developer applications that add value and benefits to our buyers and sellers. Finally, we want to continue transforming our business by exposing valuable eBay solutions and capabilities to empower developers.