Adopting an API-First Strategy to Empower Developers – InApps Technology 2022

We are in a digital age that requires interacting with customers more efficiently and more frequently, which helps explain why most organizations now consider APIs (application programming interfaces) fundamental to their success. In eBay’s experience, an “API-first” mentality — focusing on developer needs, designing APIs before implementation and treating the API as a product — has made a massive difference.

API as a Product

APIs are necessary for building and connecting applications. Today, however, APIs are more than just software talking to other software. At eBay, our partners expand our business by creating fantastic experiences for their buyers and sellers, who, in the end, are our mutual customers. We continue to unlock new integration models and revenue opportunities via our APIs.

At eBay, APIs are built by developers for developers. We treat them as first-class products, which means that they are designed, implemented and maintained in such a way to give our API customers — developers — a good experience.

For example, to deliver a more engaging shopping experience to our buyers, we are rolling out new video capabilities. We recently released a new Media API to allow third-party developers to enable sellers to showcase products and brands and drive sales by uploading relevant videos. This is an example of our API-first strategy. We have been hearing from our developer community about the importance of getting early access to our products and initiatives. We focused on developer needs, collaborated with stakeholders, designed the contract first, reviewed it with trusted developers and finally released our product. The new API is the only channel to upload videos to eBay at present.

API-First

“Simplicity is the ultimate sophistication” – Leonardo Da Vinci

An API-first mentality is not only about the APIs themselves, but also about the use cases, capabilities and actors who benefit from new features. Developers are looking for capabilities, so we are talking about launching a product rather than releasing an API. It is important to zoom out and see the bigger picture.

Therefore, when working on APIs it is essential to:

• Understand the customer problem and design around that.
• Not expose internal implementation details in your interface.

Many organizations start from the bottom up and design around internal implementation details without considering consumers, abstracting concepts or hiding the underlying complexities. APIs define what consumers can do, and the database is not an API contract. API owners also sometimes optimize for their engineers and ignore third-party developers by using internal vocabulary, trying to save on the number of methods and endpoints, pushing data interpretation to consumers, etc.

Instead, everyone involved in API design needs to focus on taking the complex and making it simple. Thinking about capabilities upfront is a prerequisite for ensuring that business and technology strategies are aligned.

At eBay, we start with our interface design method (IDM) to arrive at a stable contract. It begins with describing use cases through specifying actors, actions and constraints. The next step is to derive the entity relationships. Nouns are then identified from the entities and verbs from the actions. The final phase is determining resource representations and specifying authorization details. Once all this is done, the easiest part is now to map it into RESTful endpoints and methods.

To be most effective, the focus needs to be on a consumer-centric approach. A good, readable, predictable, intuitive and easy-to-understand API will make developers of all shapes and sizes more productive and efficient.

Consistency

To enable ease of use for developers, each API needs to fit into an overall API portfolio. At eBay, we have an API taxonomy that we defined several years ago when we started revamping our developer program. We grouped our APIs into four contexts:

• Sell allows sellers to manage their business on eBay.
• Buy exposes inventory and enables transactions from any partner experience.
• Commerce has capabilities that are common to both Buy and Sell use cases.
• Developer provides developers with insights into their integration with eBay APIs.

Standards and patterns define what is constant across the APIs and make it easier for developers to integrate. We rely on existing industry standards and patterns and also define our own. This approach brings agility and speed to the API development process as well as consistency of the API portfolio.

But consistency is not only about specs and patterns; vocabulary consistency is equally important. For example, an item is an item across the API portfolio. Using consistent terminology and understandable names while avoiding internal acronyms makes an API easy to discover and consume.

In addition to the way things are named, the API should do what it says it does. An endpoint is like a sentence where resources are nouns and HTTP methods are verbs. It conveys both purpose and intent. For example, this method creates a new return policy for a seller without modifying the seller’s existing listings:

POST sell/account/v1/return_policy

All the APIs must be good citizens to avoid confusion and developer inefficiency, and a proper governance process can help to ensure that. It is all about making the right choices for the developer program, so it is essential to leverage governance as an enabler rather than as a gate. The focus of governance should be on the “what” part vs. the “how” part. This approach gives engineers some creative freedom. At the same time, developers can integrate with standardized and consistent APIs that implement cross-cutting concerns such as authorization, API rate limits, and error handling in the same way. This improves developer productivity and creates a good developer experience.

Developer Experience

Delivering an API is only half the work. The overall developer experience is part of the release too. For example, documentation must be accurate and efficient. Developers do not have time to spend hours reading documents, so it is important to keep documentation brief, concise and accurate.

The OpenAPI specification is now an industry standard for describing APIs and is open source with a large developer community. Many tools, such as Swagger, generate clients from the OpenAPI documents. By publishing API contracts using the OpenAPI specification, we enable our developers to integrate with your APIs in no time.

Feedback Loop

“When you know better, you do better.” – Maya Angelou

Direct feedback from customers helps to shape API strategies and roadmaps. At the end of the day, APIs are for developers, so delivering what will work for them is crucial. Working directly with customers also helps build long-term relationships by delivering what they ask for.

In addition, soliciting feedback early allows API providers to optimize their engineering efforts. Instead of jumping into the implementation immediately, the design-first method allows engineers to rapidly change the interface while iterating with customers. A good practice is to proceed with public beta or private beta releases before broader release. Focus on your trusted developers to gather feedback and do so as often and as early as possible.

Sometimes it takes time to iterate, but in the long run it is faster to follow the “measure twice, cut once” approach to refine the APIs. (In some parts of the world, they even say measure seven times, cut once!) It is more efficient to deliver an API that we know will meet developer needs instead of having to redo it six months later.

Indirect feedback is equally important. APIs contribute to business objectives, so analyzing API usage and measuring the APIs’ outcomes and performance are equally important. Developers shape your products, so to understand which way to go, it is important to look into the data and use analytics to improve the overall API portfolio. At eBay, this is one of the main drivers to enhancing the APIs. Over time, some of the APIs have been deprecated and decommissioned while others flourish with numerous minor and major releases. That is how it should be — thriving API ecosystems are flexible and adaptable.

Continuous Architecture

“The only thing that is constant is change.” – Heraclitus

An API-first strategy enables an agile business, adds implementation flexibility and is a prerequisite for being great at e-commerce. Treat your APIs as products and maintain them. Define standards and emphasize governance, but be flexible on the “how” part to give teams some creative freedom. For us in the developer ecosystem organization at eBay, flexibility and joy are key to engineers feeling safe to focus on customers, take risks and innovate.

Interested in pursuing a career at eBay? We are hiring! To see our current job openings, please visit: http://ebay.to/Careers

Featured image via Pixabay.