How to enhance your API-first design process

Arnaud Lauret

March 27, 2023

An API-first design should be reusable, interoperable, modifiable, user-friendly, secure, efficient, pragmatic, and—crucially—aligned with the organization’s goals. These essential traits will ensure the API can effectively contribute to the API-first organizational strategy and development model, in which APIs are prioritized to deliver maximum value to the business. But what can be done to produce such an API design?

In this post, we’ll explore how you can achieve an API-first design by integrating the following five actions into your API design process:

• Use natural language to analyze and challenge needs
• Observe context and identify constraints
• Fully describe and document your APIs
• Leverage existing APIs and guidelines
• Integrate automated and human feedback loops into the process

Use natural language to analyze and challenge needs

To ensure you’re creating the proper API that is aligned with your organization’s goals, you must use natural language to deeply analyze the needs (if you use Postman’s API lifecycle, you will have identified these needs during the “define” stage). This analysis, which may involve listing consumers or end-users, their use cases, and how to achieve them, is essential for identifying every API feature or operation that is necessary to fulfill the needs. Once you’ve conducted this partial or final analysis, you should challenge expectations with stakeholders to ensure alignment.

It’s important for this analysis to be conducted using only natural language—without thinking about the programming interface representation. Separating concerns in this way will facilitate discussions with subject matter experts and help you avoid premature debates over issues like /customers vs. /customer or PUT vs. POST. Ultimately, you may realize there are better options than the standard REST API; for instance, a gRPC, asynchronous, or GraphQL API may be a better fit.

Observe context and identify constraints

API designers and stakeholders must observe the API’s context and identify any constraints to ensure the API design will be pragmatic, efficient, and secure. This may involve asking questions like: When should this new API be deployed? Are there limitations in the underlying system? Does the subject matter fit our usual approach to creating APIs? What are the security requirements?

Next, API designers and stakeholders can decide whether to conceal or integrate the constraints in the design. Hiding them may lead to additional work but a better design. On the other hand, incorporating them may reduce the API’s quality but make it easier to meet a deadline. It’s important to remember, however, that security is a non-negotiable concern.

Fully describe and document your APIs

Comprehensively documenting and describing an API during the design process is essential for ensuring you capture all information—such as programming interface descriptions, needs and their analysis, constraints, and security requirements. It can also guide you towards creating the proper API.

To describe and document an API, you can easily use API specifications such as OpenAPI, AsyncAPI, GraphQL schema, or JSON Schema. These specifications will give you a frame, but they can only be used to document an API’s elements—not how consumers can combine them to achieve the use cases identified during the needs analysis. You can leverage Postman Collections and Flows to fill this gap. These features can be an excellent addition to early API documentation, as they can be used to describe how to fulfill use cases with a series of API calls.

Whatever format you use, it’s crucial to connect the needs analysis and the resulting API to ensure you’re not missing anything in the final design. It’s also essential to provide as much information as possible to the implementers, which helps ensure the implementation will match the expectations. For instance, in an OpenAPI document, you can confirm that the “search customers” operation that was identified during the needs analysis has been turned into GET /customers by reviewing the operation’s summary. You can also review the operation’s security configuration and response description to ensure it only returns the customers within the user’s or consumer’s scope.

Leverage existing APIs and guidelines to simplify decision-making

The API design process involves making tons of decisions. Nevertheless, many of these decisions will always be the same because all APIs will ultimately deal with the same fundamental concerns, such as the best way to represent a date or an amount of money, or how to search a catalog, create a resource, or start a process. Additionally, all APIs within an organization must share a common look and behavior.

To avoid losing time to long, repetitive discussions or reinventing the wheel, you can take advantage of your organization’s other APIs and reproduce their design patterns. Still, it will be more efficient to formalize those patterns in guidelines that describe common “recipes,” such as “how to design a search operation” or “how to manage file upload.” API guidelines can cover various topics, from user-friendliness to security, but they should only exist to contribute to creating an API-first design. If anything a guideline prescribes does not advance that goal, you should remove it.

Guidelines allow you to quickly achieve an API design with a certain level of user-friendliness, interoperability, evolving capability, security, and efficiency. But most importantly, they help you focus on the actual subject—creating the right API—without getting distracted or wasting time with rhetorical questions.

Integrate human and automated feedback loops into the process

Even when guidelines cover all relevant topics in the most user-friendly manner, some API designers may never read them. Other stakeholders may slow down the process by repeatedly checking details in the guidelines. Additionally, anyone can make tiny mistakes in their programming interface design.

API definition linting, when used while designing the API and in CI/CD pipelines, can help you save time and avoid many mistakes. These automated checks can identify errors that need to be fixed or suspicious design patterns that require attention. For instance, you won’t have to worry about missing security configurations, missing or incorrect pagination on a search operation, or heterogenous name casings. And if you decide a query parameter should be required even though your guidelines say it shouldn’t, you’ll make that decision willingly (although you really shouldn’t do that).

API linting can help you significantly, but it cannot do everything. For instance, it will not be able to confirm that your API is 100% user-friendly, and it can’t tell you whether you’re creating the right API. That’s why it’s important to seek iterative feedback from your colleagues, subject matter experts, and future consumers as early as possible. Sharing your extended API documentation with them, as well as mocks, will help ensure they have what they need to give constructive, effective feedback.