API design

What are the key stages of API design?

There are four key steps in the API design process that every organization should follow. Each step requires collaboration between stakeholders—such as business leaders, developers, consumers, and partners—to ensure that the API meets all relevant needs. Collaborating at every step of the API design process also helps developers avoid building unnecessary functionality. These steps are:

Step 1: Determine what the API is intended to do

The first step in the API design process is for all stakeholders to agree on the API's business use case. An API that is responsible for an authentication workflow will have different requirements than an API that allows a user to browse a product catalog, so it's important to align on the use case before making any other decisions. The use case may also have implications on the type of architecture you choose. For instance, a gRPC-based architecture might make the most sense for an API that connects internal microservices, while a GraphQL API would be well-suited for a service that relies on disparate data sources. Once in agreement, stakeholders should clearly outline their goals for the API by describing—in natural language—exactly how it will meet specific needs.

Step 2: Define the API contract with a specification

Once all stakeholders are aligned on the API's use case, you will need to decide which resources are required, how their data should be formatted and structured, how they should relate to one another, and which methods should be available on their associated endpoints. It's also important to determine the desired levels of abstraction and encapsulation in your API, which will help you strike a balance between reusability and legibility.

These decisions should be captured in an API definition, which is a human- and machine-readable representation of an API's intended functionality. API definitions adhere to API specifications, such as OpenAPI and AsyncAPI, which provide a standardized format for API definitions and lay the foundation for API contracts, documentation, mocks, and tests.

Step 3: Validate your assumptions with mocks and tests

Once you've completed your API definition, you can use it to generate mock servers. Mock servers return sample data in response to requests, which enables you to confirm that your API will work as you intend it to. Mocks can also be used alongside API tests, which can be run manually, on a schedule, or automatically within CI/CD pipelines. Testing and mocking during the API design process will help you catch and remediate any issues before they find their way into your consumers' codebases, when they are much more difficult to fix.

We'll discuss mock servers in more detail in a later section.

Step 4: Document the API

The last step in the API design process is to write documentation. This step, which involves defining key details about every resource, method, parameter, and path, helps validate the design and ensure that consumers are able to start using your API as quickly as possible. Documentation might also include examples of API requests and responses, which give consumers crucial insight into how a particular API supports common business needs. Some tools can automatically generate documentation from an API definition, so teams don't have to worry about their documentation becoming outdated.

What is the role of mocking in API design?

Mocking, which involves setting up mock servers to return sample data in response to API requests, is a crucial part of the API design process. Mocks can be introduced as soon as your definition is complete, which means they can be used alongside tests to validate design choices and confirm that your API will work as expected. Mocking not only enables API consumers to start integrating an API while it is still in development, but also reduces pressure on API producers to publish an implementation that is buggy or incomplete. This benefit allows producers and consumers of internal APIs to work concurrently, which significantly reduces the time to market.

Why use Postman for API design?

The Postman API Platform, which was ranked the best tool for API design by G2, comes equipped with a robust suite of features that can help teams implement mature API design processes. With Postman, you can:

• Generate and edit API definitions: Postman enables you to import an existing API definition or generate a new one from scratch. Postman supports OpenAPI, RAML, Protobuf, GraphQL, or WSDL definitions, so you can choose the specification that works best for you.
• Document your API: Postman automatically generates documentation for any collection, as well as for any OpenAPI 3.0 definition. Your documentation will update automatically as you make changes, ensuring that your documentation remains useful to consumers.
• Build, run, and automate API contract tests: Postman provides a library of customizable code snippets that can be used to create API contract tests. You can run tests manually within Postman—or use Newman or the Postman CLI to run them automatically within your CI/CD pipeline.
• Simulate API behavior with mock servers: Postman enables you to set up mock servers that will return sample data in response to requests—even if your API isn't in production yet. This allows producers to validate their assumptions without rushing development, while giving consumers a jump start in the integration process.
• Collaborate across your organization: Collaboration is central to Postman's DNA, and Postman users can leverage team workspaces to easily collaborate on API projects. Postman also supports commenting across the platform, which reduces friction by allowing teams to communicate in the same place where they do their work. Finally, Postman is intuitive and user-friendly, which makes it accessible to developers and business stakeholders alike.