Best Practices and Principles for API Design

What is an API?

API stands for Application Programming Interface, which is a mechanism that allows the interaction between two applications using a set of rules.

APIs are beneficial because they allow developers to add specific functionality to an application, without having to write all of the code themselves. APIs also allow developers to access data from other applications. For example, when bloggers put their Twitter handle on their blog’s sidebar, WordPress enables this by using Twitter’s API.

Main types of Web APIs

There are four main types of APIs:

• Open APIs: Also known as Public API, there are no restrictions to access these types of APIs because they are publicly available.
• Partner APIs: A developer needs specific rights or licenses in order to access this type of API because they are not available to the public.
• Internal APIs: Also known as Private APIs, only internal systems expose this type of API. These are usually designed for internal use within a company. The company uses this type of API among the different internal teams to be able to improve its products and services.
• Composite APIs: This type of API combines different data and service APIs. It is a sequence of tasks that run synchronously as a result of the execution, and not at the request of a task. Its main uses are to speed up the process of execution and improve the performance of the listeners in the web interfaces.

Web service APIs

Apart from the main web APIs, there are also web service APIs:

• SOAP
• XML-RPC
• JSON-RPC
• REST

A web service is a system or software that uses an address, i.e., URL on the World Wide Web, to provide access to its services.

The following are the most common types of web service APIs:

• SOAP (Simple Object Access Protocol): This is a protocol that uses XML as a format to transfer data. Its main function is to define the structure of the messages and methods of communication. It also uses WSDL, or Web Services Definition Language, in a machine-readable document to publish a definition of its interface.
• XML-RPC: This is a protocol that uses a specific XML format to transfer data compared to SOAP that uses a proprietary XML format. It is also older than SOAP. XML-RPC uses minimum bandwidth and is much simpler than SOAP. Example

<employees>
  <employee>
    <firstName>Becky</firstName> <lastName>Smith</lastName>

• JSON-RPC: This protocol is similar to XML-RPC but instead of using XML format to transfer data it uses JSON. Example

{"employees":[
 { "firstName":"Becky", "lastName":"Smith" },

• REST (Representational State Transfer): REST is not a protocol like the other web services, instead, it is a set of architectural principles. The REST service needs to have certain characteristics, including simple interfaces, which are resources identified easily within the request and manipulation of resources using the interface.

What are the differences between SOAP and REST?

SOAP	REST
It has strict rules and advanced security to follow.	There are loose guidelines to follow allowing developers to make recommendations easily
It is driven by Function	It is driven by Data
It requires more Bandwidth	It requires minimum Bandwidth

What are the differences between JSON and XML?

JSON	XML
Supports only text and numbers.	Supports various types of data for example text, numbers, images, graphs, charts etc.
Focuses mainly on Data	Focuses mainly on Document.
It has low security	It has more security

Types of APIs

Below is a list of API architectures, specifications, frameworks, and protocols.

As a general note, we are talking about web-APIs, although APIs are not only web-based. There are APIs for desktop applications or browser applications. Essentially, any application can have an interface for other applications.

RESTful APIs follow the Representational State Transfer (REST) architecture outlined by Roy Fielding in 2000. It uses a subset of HTTP and is what we’ll be defining in this tutorial.

SOAP stands for Simple Object Access Protocol and uses XML as a format to transfer data. It outlines message structure and methods of communication. To define a SOAP API, you use the Web Services Definition Language (WSDL), a machine-readable document, to publish a definition of its interface.

Apache Kafka is “… an open-source distributed event streaming platform …”. It uses a series of APIs to facilitate the communication for applications with event-driven architectures (EDA).

Websocket APIs use the Websocket API exposed in browsers to open up a two-way interactive conversation between the browser and API (server) . WebSocket APIs are used for event-driven driven architectures and are the focus of the AsynchAPI initiative. MDN has a wonderful guide on writing WebSocket servers.

AsynchAPI is an organization building tools and authoring the AsynchAPI specification for event-driven architectures. They plan to create the industry standard for asynchronous API specifications.

XML-RPC,  “… is a protocol that uses a specific XML format to transfer data compared to SOAP that uses a proprietary XML format.”

JSON-RPC, “… is similar to XML-RPC but instead of using XML format to transfer data it uses JSON.”

Think About Consumers

First, we are designing an interface. It’s for applications, but other people (consumers) need to understand and navigate the interface. The author Peter Morville outlined several adjectives to think about when designing user interfaces. However, they can help us with API design, too.

• Usable
• Findable
• Valuable
• Credible
• Useful
• Desirable
• Accessible

These adjectives (part of the UX Honeycomb) remind us to think about the other parties in the design process.

Second, an API route works like a function. Therefore, you interact with it like a contract:

1. The API defines the resource’s location, who can access it, and what you provide to receive the resource.
2. The consumer locates the resource and (if they can access it) provide the required parameters.

Similarly to programming, the function (API route) should not do more than is necessary. Ideally, a route/method combination should do one thing. Later, we could add parameters to enable subsequent features, but we want the function to be simple.

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.

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 built.

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 implementation. 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:

1. Research to see if your API already exists in part or whole. It could save you time.
2. 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.
3. Most have machine-readable specifications (i.e., OAS, AsynchAPI). Again, common specifications probably can handle your use case.
4. 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.

Platform Independence

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.

Service Evolution

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.”. 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 (v2).

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, https://productName.com/api/.

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 /getUser, or /fetchPets.

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 examples. 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 code. 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 object. 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 content. Common content-types are:

• application/json
• application/xml
• image/png
• text/html; charset=UTF-8
• text/csv

Support partial responses for large resources. 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 paginating. 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.

1. Choose an approach
   1. 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.
   2. If you choose to design first, continue to the next step.
2. Define the goals, resources, actions, and intent of the API.
3. Select a name, URL, version, security protocols, and define servers.
4. Define routes with descriptions, parameters, schema, headers, and examples (i.e., parameters, request body, response object).
5. Collaborate with your team to ensure that the decisions for the contract are practical.
6. Use the feedback to make modifications to the specification.
7. 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

RapidAPI recently joined up with Paw to add API design to their array of product services. You can get started with RapidAPI Design by Paw for free by signing up for the beta.

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

Postman offers API design in their application that helps users define, develop, test, and monitor APIs.

The application has an editor to define OpenAPI, RAML, and GraphQL specifications. You can also import specifications that you already have to generate collections.

Swaggerhub

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 users.

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.

AsynchAPI Playground

The AsynchAPI specification is the industry standard for asynchronous APIs that are part of event-driven architectures.

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.

What is API Architecture?

API architecture refers to a software building block that implements an API. For example, if we look at the TCP/IP protocol, many layers form the building block of this protocol stack. They are all arranged in a specific order. Individually, they perform a single, well-defined responsibility. But, collectively, they achieve the transmission of data between two devices through the Internet.

It is possible to envisage an API architecture in the same way. However, before getting to that, defining the core responsibilities of an API is crucial. 

As evident from its acronym, an API provides a mechanism for invoking a task on another system. There are four primary responsibilities of an API.

1. Interfacing: The interface defines the specifications for accessing the API. In the context of a web API, this interface defines the protocol specifications for accessing the API over the Internet. 
2. Interpretation: The data sent as part of an API request and response is subjected to interpretation. This is done to take additional actions or translate between human and machine, user and platform interpretable data formats. 
3. Computing: As part of its core function, an API executes a business logic. Therefore it requires a computing environment.
4. Data Processing: All applications rely on some data store that necessitates transfer, dump, or fetching of loads of data. An API relies on these operations too.  

Building Blocks of an API Architecture

To better understand the API architecture, let us split the API responsibilities into individual entities accountable for them. In this way, we stitch the building blocks that define the generic API architecture.

API Interface Block

The Interface block is responsible for defining the specifications for the API. This is important for the external world to access the API. In most cases, these specifications are governed by the application layer protocol that hosts the API. 

HTTP is the most ubiquitous protocol that carries the API payload. Therefore the API interface is defined in terms of the API endpoint URL, the port number, and the HTTP method. The API interface also defines additional HTTP headers. 

One of the other popular protocols is MQTT. It is based on the publish-subscribe pattern and makes it easy to build async APIs. In this case, the API endpoints are identified by a topic name instead of the URL.  

API Controller Block

Beyond the interface, an API needs to control the ingress and egress traffic. This is where the API request and responses are interpreted, and additional control mechanisms are applied via the Controller block.

Some of the most apparent control mechanisms include rate limiting, throttling, blacklisting. This is to ensure that the client applications do not misuse the API. It also guards against abuse of the API.

Even more important is the handling of unauthorized access to API. Therefore this building block is also responsible for authentication and authorization. Additionally, it has the ability to peek inside the HTTP headers and data payloads to perform additional checks and transformations.

API Runtime Block

The Runtime block takes care of the computing responsibility of the API.

Behind the scenes, every API is a piece of software that performs a well-defined business logic serving the needs of the API’s client. 

Depending upon a chosen programming language and its toolchain,  a runtime environment gets spawned. Then, the business logic execution happens inside this runtime environment, supported by additional configuration data and environment variables. 

API Data Bridge Block

Usually, the data storage engines, like the databases or any form of data store, are universally shared between the individual APIs that form the  API service. This approach ensures that there is a single source of truth across all APIs. The APIs must have a bridge between their runtime block and the data engine to facilitate seamless access to data. 

The Data Bridge block is responsible for orchestrating this data access. The actual implementation of this block is platform-specific and depends on database drives and programming libraries. These are managed from within the Runtime block.

Additional Components of API Architecture

What we covered until now is the architecture of a single API. However, APIs do not live in isolation. Instead, an individual API is a part of the API service, with many API endpoints, each having its path and request, response semantics. Additionally, a software built around APIs might leverage multiple such API services.

Therefore, big picture thinking is required for the overall architecture of API service.  

API Management

API management refers to the overarching administrative processes for managing multiple APIs. It involves several interventions to manage the entire lifecycle of APIs. 

API management is an integral part of any API-led strategy within an enterprise. It is facilitated via an API management platform that oversees all the administration, deployment, and monitoring of APIs. It also orchestrates the coordination between the API developers, consumers, and the operations teams.  

Service Mesh    

A service mesh is like a common logic fabric that connects multiple APIs.

In the development of any software, many commonalities emerge out of the overall business logic. These are bunched into a set of standard modules reusable across multiple components. 

This principle applies to API-led software development as well. A suite of API services will have many APIs that criss-cross each other due to the interdependence of common business logic. Therefore, service mesh acts like an intermediary sub-system that allows APIs to talk to each other in a well-coordinated manner.          

Choosing and deploying a service mesh is essential to scale API services. Above all, it provides a robust framework to deploy service-wide API architecture. 

Security    

The basic authentication and authorization handled by the API Controller block takes care of access security. But it does not guard against some of the more significant security threats on the Internet.

Malicious personalities frequently adopt DDoS (Distributed Denial of Service), man-in-the-middle, and other organized hacking attempts to disrupt the API services and steal information. Therefore, the API architecture must add additional security layers to handle such macro-level security threats.

API Architecture Best Practices For Deployment

The architecture of any system defines the internal sub-system, component level arrangement to ensure smooth functioning. But when the rubber meets the road, that is the actual test. 

The same applies to APIs as well. Despite the best architectural choices, the API service as a whole must perform well in a real-world deployment. Here are a few guidelines to consider. 

API Modelling     

API modeling defines how the APIs mimic the real-world service that they represent. REST is the most ubiquitous way of modeling APIs. It is a prescriptive framework for designing API. It lays out guidelines to balance the API semantics and functionality such that the APIs model the real-world application.   

Most importantly, REST allows the individual APIs to have distinct separation of concerns, suitable for modular architecture.

Hosting Considerations

APIs are hosted under various server configurations. Many options exist between the server and serverless setup, each having its pros and cons. 

However, it is imperative to choose a hosting configuration that augurs the business goals for the API service.  While the API architecture is agnostic of this decision, the overall cost vs. performance tradeoff is undoubtedly a matter of consideration. 

Scalability

The projected traffic for any API service is always a challenge to foresee. Whether it is about handling growth or seasonal fluctuations, the API requests and responses have to be channeled so that the API service is elastic enough to handle extreme limits in traffic variations.   

These circumstances call for having an additional deployment architecture that can handle scale. It is an outer layer of computing fabric that encapsulates the API architecture and helps it scale horizontally.

What is an API Gateway?

An API Gateway (a key part of API management) is the programming element that orchestrates and coordinates how various requests are processed in a microservice architecture. It sits at the front of the API and acts as a single entry point into a system allowing multiple APIs to function cohesively and offer a smooth experience to the user. Typically, an API Gateway handles a request by invoking several microservices and aggregating the results to identify the best path. And since a gateway is responsible for protocol translations, using an API kind of front-end programming is vitally essential for computer applications (clients) that are built with microservices that utilize multiple, disparate APIs.

An API Gateway features an HTTP server where routes are associated with a FaaS function or a microservice. When the API Gateway receives a request, it checks up to see which services are needed and combines them to form a synchronous experience for the user. It maps the request’s parameters to the input arguments of the service or function, to establish a high starting point. The most critical role of the API Gateway is to facilitate reliable processing of all API calls. Additionally, it also helps to provide enterprise-grade security, design API specs, and manage APIs centrally.

Since developers are required to update the API Gateway when a new microservice is added or removed, it is vitally essential for the updating process to be as lightweight as possible. Therefore, when evaluating API gateways, developers should consider which outstanding features that have been added by the vendor to differentiate their product from the rest.

API Gateway Tasks

Besides the routing task, an API gateway also allows the implementation of other tasks such as:

1. Load Balancing

Load balancing is a technique that is designed to distribute workloads uniformly to optimize work efficiency and maximize network capacity. An API Gateway keeps track of all requests and attains a perfect balance when loading them to different nodes of a particular service.

2. Authentication

An API Gateway can also help authenticate API calls from outside, thereby help to improve security and lower the network latency.

3. Request Dispatching and Service Discovery

By receiving calls and waiting for results from all services, a gateway can combine results and send them back to the client, thereby simplifying the communication process between the client and a microservice. Additionally, it can determine the necessary response time for all requests, and route the priority API calls to the most expedited responding node.

4. Acting as a Circuit Breaker

An API Gateway can also aid in rectifying a partial failure through what is referred to as circuit breaker pattern. This is when the gateway curtails data transfer to a failing component when a specific threshold has been reached. This gives developers enough time to evaluate the logs, fix the hitch, or update the components.

5. Facilitating Cache Management

Cache management is another common API Gateway feature. Typically, an API Gateway will allow you to configure cache settings to improve API performance and reduce the traffic it sends to your back end. Learn more about caches and how they pertain to APIs.

Why Use an API Gateway?

The most significant benefit of using API gateways is that they permit developers to encapsulate the internal structure in several ways. Besides accommodating requests, gateways can be utilized to call multiple back-end services and aggregate the results. Developers can also use API gateways for the following reasons:

• They enhance the security of your microservices
• They facilitate the support for combining communication protocols.
• They help mock or virtualize services to assist in integration testing or validate design requirements.
• To decrease microservice complexities and maintain focus on the core tasks at hand.

API Gateway Example

A perfect example of an API Gateway is the Netflix API. Because the Netflix streaming service is available on a diverse range of devices including smartphones, blue-ray players, and televisions, their attempt to use a one-size-fits-all API style proved futile. Therefore, they had to use an API Gateway that implements a separate API for every device.

API Design Principles

Principles inform best practices. The best practices may change, but principles persist over time. This does not mean that principles are immutable. However, like a compass, they allow designers to navigate new space while keeping their bearings.

In this section, let’s explore some API design principles in depth.

Choose an API Approach

Choosing an approach to API design is a principle because some level of planning should always be a principle. The two types of approaches when designing APIs are:

1. Design-first
2. Code-first

Design First

Design first approaches try to represent the API in a specification before writing the code. Common API specifications include:

• OpenAPI or OAS (RESTful APIs)
• RAML (RESTful APIs)
• AsynchAPI (WebSocket APIs)

The specification becomes the blueprint for the API and contains information like:

• protocols
• schemas
• parameters
• headers
• operations

More importantly, the specification is machine-readable. This allows API tools to consume the specification to generate documentation, tests, API clients, and mock APIs.

Next, let’s compare some of the specifications listed above.

OpenAPI and RAML

Both specifications are designed for use with RESTful API architectures. Furthermore, looking at the two specifications side-by-side may not show any obvious differences because they both use YAML (although you can also represent OpenAPI in JSON).

Additionally, both specs are based on HTTP, so they have similarities in defining routes, parameters, and response objects. The main difference between the two specifications is that RAML focuses on code reusability.

The specification has an !includes operator that pulls in data objects (i.e., response objects) from other files. This means that schemas or data objects are more reusable across specifications.

That said, RAML is not a clear winner over OAS. Both specifications are widely used and supported. Furthermore, Uri Sarid, co-author of RAML and CTO of Mulesoft, has written, “To explicitly bridge these two approaches [RAML and OAS], MuleSoft has built an open-source API Modeling Framework (AMF), available now under the Apache License, which reads and writes both RAML and OAS. […] we [Mulesoft] are explicitly committing to interoperability between RAML as a modeling language and OAS as a description language.”

OpenAPI and AsynchAPI

Unlike the comparison to RAML, the AsynchAPI specification is for a different type of API than OpenAPI. Below is a helpful graphic from AsynchAPI’s documentation comparing the two specifications.

You don’t need to understand AsynchAPI to see the similarities. Not coincidently, many parts of the AsynchAPI specification were based on the OpenAPI specification⁵.

AsyncAPI is an open source initiative that seeks to improve the current state of Event-Driven Architectures (EDA). Our long-term goal is to make working with EDAs as easy as it is to work with REST APIs.

AsynchAPI Docs, Getting Started

Therefore, if you’re building an API for real-time data that handles the interaction between publishers and subscribers, the AsynchAPI specification could be your choice.

Code First

In a code-first approach, business requirements guide the code implementation. You may be thinking, why would anyone code first when they could just plan it out?

Code first approaches are similar to how an agile team may work to tackle complex business requirements. It may be a waste of time to plan out an entire API specification, only to use 5% of the original plan. There may not be a pre-made specification, but there is still planning with user stories and requirements.

An example of an emerging technology that focuses on a code-first approach is the Python framework FastAPI. The framework builds the OpenAPI specification as you develop routes or create response schemas.

Code first approaches do not abandon API specifications. Instead, they use tools to generate the specification as they are building or after they complete the API build.

Design APIs Around Resources

The adage to design APIs around resources is nested in how the internet is set up. The internet has verbs, built-in, that describe actions performed by API requests. We’ll provide more explanations and examples on this topic in the best practices section.

It’s important to identify the resources that an API facilitates. In a previous article, I described a simple resource like a User or a Pet. These examples were based on the common Swagger Pet Store example specification. However, it’s typically not that easy and straightforward.

Regardless, even with an API that performs AI or statistical inference, we can locate the resource as the model. It might be helpful to look for the nouns that are involved with the API.

Nested Resources

It’s difficult to find a consensus on nesting resources with APIs. An example of nested resources could be /user/jarrett/pet/{petId}, where a user has the nested resource pets.

Consequently, I cannot give you a clear principle, but there are some guidelines on different ways to nest them. The only principle to draw from nested resources is to nest with caution. In the best practices section, we’ll talk more about nested resources.

Don’t Repeat Yourself or Others

In this article, we mentioned two types of specifications for REST APIs. Also, we talked about AsynchAPI specification for event-driven architectures (another common event-driven architecture technology is Apache Kafka).

The amount of tooling, technological help, and add-on technology, like GraphQL, is enormous for APIs. The web API ecosystem has grown over the past two decades to automate and improve APIs’ design, development, and implementation.

Not repeating yourself is a principle of software development, but it applies equally to API design. For example, reusability is already built into specifications, like RAML.

It’s probably unlikely that you will need to invent an architecture, redesign how the web interfaces with your API, or create your own API specification. In API design, remember to leverage the technologies available (many of which are open source).

Platform Independence

Interacting with an API should not depend on the type of client application. In other words, the API’s internal workings should not reject client interactions because of the operating system or programming language.

You can achieve platform independence by following standard protocols and defining a data change format.

Service Evolution

The principle of designing for service evolution comes from the layer of abstraction that the web provides. We can change what the API route is doing without changing the URL for the route, the type of returned data, or how the client interacts with the interface.

For example, one of the REST architectural properties is the “…modifiability of components to meet changing needs (even while the application is running)”.

There might be a personality score for a user at the URL http://api.example.com/user/personality-score. Over time, we discover better ways to calculate that score or even have a proxy server that sends the data to a microservice. The point being, we have many possibilities for how we can achieve calculating the score. Regardless of our choice, the client applications will always find a score at that same URL.

The API will evolve. Therefore, it’s important not to stretch current implementation to support a trivial use case. Additionally, an API should implement some sort of versioning to account for breaking changes.

In the next section, we’ll look at best practices. I hope you can see how the practices are informed by the principles laid out in this section.

Best Practices

Keep URL Simple

Companies will keep their API as a subdomain or route on their organization domain. For example, a company named API Designers has a website https://apidesigners.org. The domain is simple, and we want to keep it that way. If API Designers had an API, we would expect it to be found at either:

• https://api.apidesigners.org
• https://apidesigners.org/api

It’s more common to see the first URL. The top URL uses a subdomain, which DNS records will direct to a different server (the API server). However, either works well for the base URL of the API.

Building on this example, let’s talk about API versioning and its place in the URL.

Include Version in URL

Although not stated, using version control with your API is a best practice. Your API specification should include the version number that the spec applies to. The version maybe 1.4.2 in the spec, but we only want the major version in the URL.

It’s only necessary to include the major version of the API in the URL because there should not be any breaking changes introduced in minor or patch versions.

It may be helpful to read about software versioning to understand this section.

Therefore, our API’s URL for version 1 should be:

https://api.apidesigners.org/v1

Using the full word version is unnecessarily verbose, and it’s understood that ‘v’ is short for version. When we launch version 2, with all-new features, the URL will be:

https://api.apidesigners.org/v2

Use Nouns and Not Verbs

The web has built-in action verbs for resources on the internet. Those verbs include GET, PUT, PATCH, POST, DELETE. Some of the verbs are easy to understand. However, often it’s easy to mix up PUT and PATCH.

Because the actions are implicit in the type of request that users send (i.e., GET, DELETE), we do not need to name the action in the URL explicitly. For example:

• Sending a GET request to api.apidesigners.org/v1/secrets will return (“get”) the data for our API design secrets.
• Sending a GET request to api.apidesigners.org/v1/sercrets/getSecrets or api.apidesigners.org/v1/fetchSecrets is redundant and considered “wrong”.

Words like fetch, get, query, and add do not belong in the URL. If you find that you’re stuck designing a route, you may need to use query parameters or read up on HTTP methods.

Use the OpenAPI or RAML Specifications for REST APIs

We have already spent some time discussing the two main specifications for REST APIs. It’s best practice to use one of the two for REST APIs because of their industry-wide adoption.

Often, you can generate the specifications before, during, or after development. This allows for flexibility in the API production workflow.

Provide Examples

Example body and request objects benefit the producers and consumers of the API. If you’re developing the API, examples become mock responses. If you’re consuming the API, example response objects help visualize the data.

An example request is different than a schema. A typical schema looks like this:

{
    "name": "string",
    "phone": "number",
    "addresses": { "object"
        "home": "string",
        "work": "string"
}

An example of the request may be,

{ 
    "name": "P Sherman",
    "phone": 2223334567, 
    "addresses": {
        "home": "42 Wallaby Way, Sydney", 
        "work": "" 
}

Providing examples in the documentation or schema is equally important for the request body.

API consumers have little control over the response object, but they are responsible for sending the proper request body. Having examples for your API may look different depending on your implementation or specification. However, most support examples for query parameters or body payload objects.

Return the Proper HTTP Status Code

HTTP status codes are a part of how the internet communicates. Like HTTP request methods, the statuses are built-in. Therefore, designers should leverage them to communicate the right information. A few examples include:

• 201 – Created
• 202 – Accepted
• 401 – Unauthorized
• 403 – Forbidden
• 406 –  Not Acceptable
• 501 – Not Implemented

The 201 – Created status code is often overlooked when creating resources through an API. It’s easy to return a 200 – OK when a client application uses a POST method to send data for a new resource.

Some of the status codes seem niche, but there are 10-15 that are extremely common. API consumers notice error codes more than they notice success codes. Moreover, there are subtle differences in the base error codes, and careful consideration is required for the correct use case:

• 400 – Bad Request
• 401 – Unauthorized
• 403 – Forbidden
• 404 – Not Found
• 405 – Method Not Allowed
• 406 –  Not Acceptable

It’s more common to inspect a status code when there’s an error. Paying attention to error types can help communication between the producers and consumers of the API.

Set the Content-Type Header for the Response

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 content . Common content-types are:

• application/json
• application/xml
• image/png
• text/html; charset=UTF-8
• text/csv

Client applications use the Accept header to inform the API of the type of data they are looking for. An API could serve different data formats at the same URI. Setting the Content-Type, combined with the client’s Accept header, opens the door for content negotiation.

Support Partial Responses for Large Resources

If you plan to serve large resources through your API, it would be best practice to support partial responses. Large response objects could cause timeouts for client applications or overwhelm their processing capabilities.

You can support large requests by setting the Accept-Ranges header for GET requests. This conveys that the GET operation supports partial requests. Then, a client application can fetch the large resource in chunks. Consequently, you’ll have to also set the Content-Length header in the response.

An example would be a large image. Other resources, possibly stored as rows in a database, should support filtering and pagination. That’s in the next section.

What’s a reasonable response size?

We can mention a smaller design principle that helps answer this question: The ideal response size for any request is the smallest possible size that contains all the information the client needs. Principles are open to interpretation and adaptation. Researching your API’s consumers could inform your design process on necessary response object size.

Support Filtering and Paginating

Most data is stored in row-like structures (relational) or document structures (non-relational). These data structures are queried in sets or by properties of the data object.

Similar to running a query in the application, the API should support query options and pagination. For resources, this could look like:

https://api.apidesigners.org/v1/secrets?specification=OAS

We query the API design secrets resource for secrets related to the OpenAPI Specification in the above example. When paginating, we can pass the parameters skip and limit to fetch data in successive requests.

https://api.apidesigners.org/v1/secrets?skip=0&limit=10

https://api.apidesigners.org/v1/secrets?skip=10&limit=25

Nested Resources

API design can become complicated when the resources contain nested resources. This is fairly common. Think of an online store that has products. Each product could have any number of reviews.

A couple of ways to design how we could fetch reviews for a product are:

• /products/{productId}/reviews
• /products/{productId}?q=reviews
• /reviews?productId={productId}

As previously mentioned in the principles section, there are arguments for and against the different approaches. However, it’s a common practice to use one of the methods in the list.

Some things to consider when choosing a nested resource model are:

• Database support for the API design
• The potential for long URLs
• Possible redundant endpoints
• Security implications for access management
• Multiple database queries for top-level and nested resources

Conclusion

API Design is an expanding topic with new ideas, tools, and practices appearing frequently. In this article, we tried to capture a handful of API design principles and best practices to guide a designer down a path that ultimately proves successful.

Additionally, API design is an ongoing process where new versions of APIs grow out of old ones. I hope you continue to iterate on your previous work to find the best solutions. Thanks for reading!

FAQs

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).

What is API management?

API management refers to administering the access, usage, and overall life cycle control of an API. It provides a mechanism to govern the traffic to multiple API services deployed for a common purpose. It also provides a developer portal wherein API producers and API consumers congregate to explore, test, and integrate APIs.

What is an API Gateway?

API Gateway is a software platform that hosts the API backend. It interfaces with the external world, the API clients and connects them with the backend business logic. In addition, it implements the API architecture guidelines and provides developer and DevOps teams with tools to build, deploy, monitor, and analyze the API’s performance.