API design is a broad topic — it’s challenging to start designing an interface for others to use. When you think of API design, you might first think of all the competing API styles out there nowadays. While most web APIs adopt REST style with JSON data formatting, some enterprises still use SOAP and XML. There’s also GraphQL, gRPC, webhooks, PubSub, and other communication protocols to consider, which utilize various ways of designing and documenting your API.

We know that technology styles are constantly evolving. But I like to think that some best practices remain relevant and transcend the technical nuances. For example, it’s generally viewed as a positive to avoid making breaking changes to avoid broken end clients. Or, you should adopt clear, consistent naming conventions for your endpoints. The developer experience also requires forethought, and it’s generally expected to provide public documentation for anyone to access. But these tips are only scratching the surface.

API design is critical and not something to place on the backburner. As such, the industry has produced a slew of best practices to follow. To dive deeper into what it means to design great APIs, we recently brought in two experts for our LiveCast on API Design Best Practices. Below, I’ll cover the highlights garnered from this session with experts Alex Akimov, Head of API Platform, Monite, and Ljubica Lazarevic, Developer Relations, Gravitee.io.

Quality Design Needs an API Style Guide

APIs are pervasive. They’re embedded into most digital applications end-users use on a daily basis. And, the rise of low-code frameworks makes it possible even for entry-level developers to create an API. But is it easy to build a good API? “No, it’s not easy at all,” said Akimov. Part of the reason lies in the fact that there is no single standard of REST, and differing API flavors tend to lead to interoperability issues.

According to Akimov, API quality hinges on an API style guide, which helps maintain consistency across a suite of APIs. The problem is that not all development teams keep an API style guide, resulting in a hodgepodge API portfolio. Another reality is that API style guides can be quite variable from business to business — something Akimov has witnessed firsthand. API style guides often conform to the company’s general programming conventions and must cater to the business logic of the use case at hand.

When starting an API style guide from scratch, “there are always new things you need to take into account,” explained Akimov. In addition to spelling out best practices (the what), API style guides should also include helpful explanations that explain why conventions exist. This will be relevant for both API consumers and developers, says Akimov. Other tips include stating the security mechanisms required, using code snippets, and linting the API style guide against a specification standard such as the OpenAPI Specification or AsyncAPI Specification.

Action Items For API Style Guides

To ensure your API style guides don’t fall short, one idea is to model yours off a successful implementation. Consider checking out the API style guides published by Zalando, Microsoft, Adidas, or Google for inspiration. There are other style guides to model listed on API Stylebook too.

Although these style guides present some helpful resources for API project managers, they fall short of representing the full spectrum of APIs in use today. For example, developer darlings Stripe, Twilio, and Amazon have yet to share their API style guides publicly. “It’s a shame they haven’t shared,” said Akimov. While one could infer these interfaces’ styles based on their public documentation and production behavior, having more open-sourced style guides can only be a positive force for the API industry as a whole.

Therefore, Akimov encourages all API providers to open source their style guides publicly on Github. He explains that this is the easiest way to give back to the API community, as it helps set consumer expectations. Such a practice could also encourage a community of enthusiasts to spot errors and work to collaborate on improvements.

To improve your use of API style guides, Akimov presents the following seven action items:

1. Open source your API style guides
2. Automate each rule with a tool like Spectral
3. Form a group of enthusiasts
4. Create a constructor
5. Take inspiration from Creative Commons
6. Make it available to everybody
7. Integrate it into the ecosystem

Before API-First, There’s Design-First

Throughout the years, we’ve tracked the rise of the API-first approach within various industries. And this trend is picking up momentum — Postman’s 2021 State of the API Report found that 67% of organizations are somewhat API-first or fully API-first. But what exactly do we mean by API-first? Well, the Postman study shed light on that as well. Most respondents define API-first as “defining and designing APIs and schema before beginning development.”

According to Lazarevic, the concept of API-first revolves around treating APIs as first-class citizens. It implies a shared understanding that today’s composable enterprise will ultimately use APIs, so we might as well develop APIs ahead of other components. The benefits of taking an API-first approach are manifold. It increases reusability and stakeholder collaboration, says Lazarevic, which in turn helps lower app development costs. Building with the potential for externalization from day one also has the power to enable an iterative development process.

Yet, “API-first is not always design-first,” reminds Lazarevic. In her work in the API space, Lazarevic has noticed two approaches emerge when software engineering divisions begin going API-first. Either teams adopt a code-first approach in which they gather business input, then code, then create API documentation after the fact. Or, they use a design-first method, in which they obtain business requirements, design the API, and then code it.

Specifications Drive Design-First

The reader is likely unsurprised as to which we feel is best — design-first is typically preferred, as it enables more streamlined communication with all stakeholders involved, says Lazarevic. A rapid feedback loop can greatly inform product-driven APIs. It also can deliver an overall better developer experience, especially when designing with cloud-based documentation and mocks.

At the heart of design-first methodologies lies the API specification. By standardizing on an API definition like OpenAPI, developer teams have a blueprint from which to work. And since nearly all API development toolsets are compatible with OpenAPI, it gives developers the ability to generate mock environments for testing purposes.

For an example of design-first principles, Lazarevic provides a sample of a simple online bookshop. Perhaps an online bookstore must design an API to enable users to browse inventory and store dispatchers to post orders. These methods and paths could easily be mocked up within a no-code GUI tool, where developers could discuss, design, and generate a definition. It could even be tested with mock data. Such a design-first setup could significantly reduce redundancy down the line and eliminate wasted resources on programming before basic functional mechanics are well-established.

Go Design-First And Embrace Style Guides

In summary, if you want to create APIs that developers love with a consistent feel company-wide, use API style guides. And, if you want to move rapidly without wasting resources, use a design-first approach founded upon an API specification.

The API-first approach means building out the APIs first, which will become the backbone for other applications and your omnichannel components. However, as our speakers have examined, there is an art to API thinking and much to consider before development begins. So, before you begin your next API project, consider how the domain will influence the structure of what you create and seek to establish consistency that also allows breathing room to innovate.