What is API Design?
API design is the process of constructing the blueprint for your API. You have the goals, objectives, and hopes for your API on sticky-notes, in emails, or in requirements. Now, you need to pull all that scattered information together into an informative representation of the result.
Good API designs anticipate questions and minimize problems. They communicate information across teams to shrink development time and let teams work asynchronously.
In this article, we’ll take a look at:
- Design principles
- Best practices
You should have a clear direction for where to go with your design next and what to look out for along the way.
API Design Principles
Difference Between Principles and Best Practices
This distinction is important and not just for API design. Principles are timeless; best practices change1.
For example, it’s considered best practice—when developing the next software version—to tag your Git commits with the next version number (i.e.,
v2.0.0). Then, after the release, the repository changes are easily found and included in release notes. However, the principle behind the best practice is version control.
Best practices are informed by principles and often change over time. Therefore, when designing APIs, remember that principles have seniority over best practices, but the best practices help you understand and abide by the principles.
API Design Principles
Choose an API Approach
Regardless of the approach you take, it should be clear that you have chosen either a code-first or design-first approach. Combining the two into a hybrid approach leads to wasted time because multiple decisions are made for the same items causing conflict.
Don’t confuse a hybrid approach with an API-first approach. An API-first approach is a type of design-first approach where a contract for how the API is supposed to work is drawn up before it’s built2.
In a design-first approach, the API is represented by a specification in a machine-readable format. In a code-first approach, business requirements guide the code implementation3. You can generate API specifications after the API is built in a code-first approach, as well.
Design APIs Around Resources
Designing APIs around a resource and the practices that stem from the adage is arguably the most important principle in API design. Therefore, the practical uses of this concept become clear in a later section. Regardless, we can still demonstrate how to think about this principle.
Many APIs are built to facilitate data. Databases implement data models to represent the underlying data structures. Consequently, we can derive a resource from a data model.
For example, one of the most common data models is a user data model. It typically has a name, phone number, and email address. A resource that would play an important role in the API is the user model. Additionally, if we also had a pet data model, we can expect to build the API around the two models, user and pet.
Don’t Repeat Yourself or Others
Possibly the most famous principle in software development is, don’t repeat yourself (DRY), and it applies to API design, as well. Similarly, it means you should not repeat things that others have done.
For example, I can’t think of a programming language that does not have some math library. Therefore, it would be a waste of time to create your own math library, given that these math libraries have been tested and are readily accessible.
In API design, the principle manifests in a few ways:
- Research to see if your API already exists in part or whole. It could save you time.
- If you decide to build, there are API architectures that will most likely fit your situation (i.e., REST, WebSocket, SOAP, GraphQL). There’s a high probability you won’t need to invent a new architecture.
- Most have machine-readable specifications (i.e., OAS, AsynchAPI). Again, common specifications probably can handle your use case.
- Utilize design tools. People have already made the syntax and design errors that you might make, and there are tools to catch errors and help guide your design.
The web is the greatest implementation of a REST API.
AsynchAPI Documentation, Event Driven Architecture
There’s no doubt that platform independence is a useful feature of the internet and web APIs. However, it only remains a feature as long as the API design does not add platform dependence.
The term API has become synonymous with web API. On the web, APIs “[…] should be able to evolve and add functionality independently from client applications.”4. This is also true in reverse.
Client applications may evolve independently of an API. Conversely, the client should not have to keep up with changes in the API’s current version. This principle implies that the API implements version control.
Best Practices for API Design
Now that we discussed design principles, we can get more specific with API design best practices.
URL Best Practices
Include version in URL. Most APIs have the major version number as part of the URL. For example,
https://api.example.com/v2/hello?search='world'. The major version is 2, and it’s found towards the beginning of the URL denoted with the letter v in front (
Keep URL simple. Similar to the previous bullet point, URLs are kept simple and short. There may be a subdomain attached to the beginning of the product URL, like
https://api.productName.com, or the API denotation can come in the form of a route,
Nouns describe routes and not verbs. The web has built-in action verbs for resources on the internet, which is why we want to design around resources. Users and pets (if you recall the earlier example) are nouns. Consequently, we can use network verbs, GET, POST, PATCH, PUT, and DELETE to perform actions on the resources.
Following this principle, it would be incorrect to have a route named
Other Best Practices
Use the OpenAPI specification for REST APIs. It’s the most common specification for REST APIs and plays well with online tools for testing, documentation, and mocking.
Provide examples6. Common API specifications, like OpenAPI or AsynchAPI, have places where you can define schemas or provide examples. These are important for front-end and back-end developers as they build to integrate with the API.
Return the proper HTTP status code6. You may know a few common HTTP status codes, like 404 – Not found. However, there is a long list of codes that communicate different messages. For example:
- 201 – Created
- 202 – Accepted
- 401 – Unauthorized
- 403 – Forbidden
Set the content-type header for the response object4. Although APIs typically communicate with JSON, there are still APIs that use XML or return file objects. The content-type header tells the client the content type of the returned content7. Common content-types are:
Support partial responses for large resources4. An alternative to this practice would be to look into GraphQL. However, the problem could persist if there is a large amount of potential data to fetch. Clients may want to limit the response size that is sent over the network to reduce latency. Supporting partial responses through query parameters could allow this feature.
Support filtering and paginating4. Likewise, it’s common for applications to improve performance by fetching data in chunks or as needed.
How to Design an API
In this section, let’s define a simplified outline for designing an API. We are going to assume that this is a REST API design process.
- Choose an approach
- If you choose to implement first, build the API based on business requirements. Then, continually check in with the customer or relevant stakeholders to ensure that the API fulfills its purpose. Finally, use a tool to examine the API to generate documentation.
- If you choose to design first, continue to the next step.
- Define the goals, resources, actions, and intent of the API.
- Select a name, URL, version, security protocols, and define servers.
- Define routes with descriptions, parameters, schema, headers, and examples (i.e., parameters, request body, response object).
- Collaborate with your team to ensure that the decisions for the contract are practical.
- Use the feedback to make modifications to the specification.
- Select API tools to publish, mock, and test the designed API.
API collaboration and design became easier the more tools became available. In the next section, we’ll look at some of the best tools for designing and collaborating on APIs.
Best API Design Tools
RapidAPI + Paw
Paw was an API design application specifically used for macOS. Now, they’ll support macOS, Linux, Windows, and web for their desktop and cloud application.
Also, the tool combines:
- RapidAPI’s intuitive interface designs
- Integration with other RapidAPI products for testing, team collaboration, monitoring, and monetization.
- Paw’s simplified API workflow
Postman offers API design in their application that helps users define, develop, test, and monitor APIs8.
The application has an editor to define OpenAPI, RAML, and GraphQL specifications. You can also import specifications that you already have to generate collections.
Compare Postman vs Paw
Swaggerhub is a SmartBear product that is useful for a design-first API approach. The online tool has error feedback when generating specifications, supports automatic mocking, and generates interactive documentation while defining the API.
The tool offers a one-user free tier for hosted docs and mocking but quickly jumps up to $75/month for collaborating with three users9.
Mulesoft API Connect
Mulesoft’s API Connect supports writing API specifications in OAS or RAML in a guided web interface. Like other platforms, once you have the specification, it can generate documentation, mock APIs, and collections.
Their API designer integrates with other services like Flow Designer or Anypoint Studio. Additionally, they have an interesting feature to build your API specification using prebuilt and reusable API fragments.
The AsynchAPI specification is the industry standard for asynchronous APIs that are part of event-driven architectures10.
One of the AsynchAPI initiative tools is a playground to generate a YAML file and see the WebSocket API’s documentation on an adjacent screen.
Learning through tutorials is one of the best ways to improve your knowledge of the subject. RapidAPI has a collection of API tutorials for common programming languages like Node, Python, and PHP.
With the addition of API design tools to RapidAPI, stay tuned for more tutorials focused on API design.
What is an API resource?
A resource is the data or service that is behind the API. This can be a user data object, pet data object, or statistical model.
What is an API contract?
API contracts are also known as specifications. They outline the interactions that client applications will have with the API.
What is API design?
API design is the process of constructing the blueprint for your API. You have the goals, objectives, and hopes for your API on sticky-notes, in emails, or in requirements. Now, you need to pull all that scattered information together into an informative representation of the end result.
What are common API architectures?
The most common API architecture is the REST API architecture. There are also SOAP, GraphQL, and WebSocket (ASynchAPI).
1 Sonmez, John. “Principles Are Timeless Best Practices Are Fads.” Simple Programmer, 17 Feb. 2013, simpleprogrammer.com/principles-are-timeless-best-practices-are-fads/. Accessed 18 Mar. 2021.
2 “Understanding the API-First Approach to Building Products.” Swagger.io, 2021, swagger.io/resources/articles/adopting-an-api-first-approach/.
3 “Design First or Code First: What’s the Best Approach to API Development?” Swagger.io, 2017, swagger.io/blog/api-design/design-first-or-code-first-api-development/. Accessed 18 Mar. 2021.
4 Narumoto, Masashi, et al. “API Design Guidance – Best Practices for Cloud Applications.” Microsoft.com, 12 Jan. 2018, docs.microsoft.com/en-us/azure/architecture/best-practices/api-design.
5 Deshpande, Tanmay. “RESTful API Design — Step by Step Guide | Hacker Noon.” Hackernoon.com, first published 12 Jan. 2018, hackernoon.com/restful-api-design-step-by-step-guide-2f2c9f9fcdbf. Accessed 18 Mar. 2021.
6 “Best Practices in API Design.” Swagger.io, 2013, swagger.io/resources/articles/best-practices-in-api-design/. Accessed 18 Mar. 2021.
7 “Content-Type.” MDN Web Docs, developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type.
8 “API Design: How to Use Postman to Design, Develop, and Test APIs.” Postman, www.postman.com/api-design/. Accessed 18 Mar. 2021.
9 “Flexible Pricing for Teams & Enterprises | SwaggerHub.” Swagger.io, 2021, swagger.io/tools/swaggerhub/pricing/. Accessed 18 Mar. 2021.
10 “AsyncAPI Initiative.” AsynchAPI Initiative, www.asyncapi.com/. Accessed 18 Mar. 2021.