APIs are necessarily a part of the whole when it comes to software systems. While each API has responsibilities and capabilities, it becomes part of the fabric that binds applications, databases, cloud services and more.
As such, API design is different than routine application design, said author and former API architect Mike Amundsen. It requires knowledge of various API-specific protocols and high-level software planning, and the ability to recognize common traps and assumptions that bring the process to a screeching halt.
Amundsen created the book Design and Build Great Web APIs as an instructive guide to the API lifecycle, including how they are designed, the specifics of builds and releases, and introductions to relevant tools. Software teams should focus on the diverse nature of APIs, good development practices and the traps that too many projects fall into.
The many sides of a single API
An API handles messaging between remote and disparate systems. Protocols standardize the way APIs request and receive data from one another. For instance, REST APIs, commonly found in web interfaces, use HTTP requests to get and consume data from other programs. But REST is just one of many protocols, such as SOAP, JSON-RPC and XML-RPC.
Amundsen highlights that API designers often create products that span different companies, and often across the globe. This usually requires the use of web APIs, which are designed for crossing distance. To meet this goal, these APIs need to account for the performance and lack of control over the systems involved in the interface. For instance, a developer can design an API to render some information for users before its processes are complete, thus masking slow requests and responses.
Teams should design APIs differently when the API must interact with applications and systems that the organization doesn't own. This means the APIs must work with various data models, for example, and serve diverse applications consuming the data. Where application developers can typically select the right database and data model for their product, API developers must instead focus on determining what information the API will need from a database, what kind of formatting the data should follow and how the API will adapt to new or unexpected request and response types.
API design best practices
Despite all the API protocols and all the design considerations that vary from one API to another, Amundsen does have some universal advice. Amundsen stressed that API design best practices are about the creation process, rather than about particular tools and protocols. Developers should always focus on solving a business problem and serving the specific needs of those that will rely on that API's function.
You do more work with APIs after release than before release.
For instance, the book's example API designed for onboarding has a specific audience: the team that manages client account activities. Even if the user group associated with an API is quite general, such as any JavaScript developer, it should drive the design. Write an API story, similar to the user story common in Agile development. User stories state the type of user, their goal and the reason for it. Amundsen advised keeping an API design at a high level. Solve design problems first, he said -- technological and tool choices should come later.
Finally, consider how the API's use in the real world will affect future design choices. Developers must add new features through versioning without breaking the API. Versioning is the process of running multiple versions of the API in production, which is necessary since teams may have to quickly revert back to earlier versions of the API if the latest iteration fails. Much like Agile cycles, the API development cycle is continuous, iterating on a minimum viable product. "You do more work with APIs after release than before release," Amundsen said, noting the departure from the classic SDLC most developers know.
API design antipatterns
Bad software development and management practices -- often referred to as antipatterns -- plague API teams just as they do application programmers. Amundsen warns that antipatterns can derail an API project.
Don't go too detailed or too ambitiously into APIs. APIs are a hot topic, and digitally enabled companies naturally want to be part of the API economy. However, too many companies will design a whole API ecosystem before they even build their first API. It's difficult to predict what will work and what won't at the outset of a project. The API economy fosters booms and busts, so it's smart to begin with a small API project and see how it turns out.
Next, don't assume that your team or organization owns each API that makes up a single application. This might be the case, but software teams deal frequently with APIs sourced from other outside companies. "You don't own them and you don't control them," Amundsen said. Think about resiliency: What happens when a component you don't control changes, or goes down?
Finally, Amundsen said that developers shouldn't get too tightly coupled to a build chain, object model or other specific approach. Even details, like overly strict naming formats, can easily derail API design. Because organizations often interact with outside APIs, developers likely will have to deal with naming formats outside their own conventions.
Inside 'Design and Build Great Web APIs'
Each chapter in Amundsen's book is divided into two parts: one that provides the high-level context needed by API project leaders and business personnel, and another that reviews the deep, technical details needed by developers. To further illustrate things, examples and exercises in each chapter are acted out by a fictional software team tasked with designing an onboarding API responsible for adding new clients, partners and accounts to a system.
In "Part II: The Design Phase," Amundsen covers how to model, design and describe web APIs. He notes:
In most companies, the API program will span many years, have lots of different people involved, and over time, use several different technologies and products. Throughout all those changes, one of the things that you can keep as a constant is your design process or method. By teaching your developers the same design method, you gain consistency without over-constraining their creativity.
A good design method also does not assume any single technology stack or tool set. That means you'll be able to grow an API program over time that is built on the power of consistent design methods and not reliant on any one API format or protocol or other technical elements. In fact, good design process makes it easier to change tooling over time without introducing incompatible implementations.
Read a longer excerpt from this section on API design here.
Design and Build Great Web APIs, ISBN: 9781680506808, copyright 2020, is available from The Pragmatic Programmers LLC. Explore the contents, including other excerpts, and purchase the book here.
