What is API design?

API design includes decisions about API endpoints, request and response formats, protocols and the way that APIs communicate with other applications and consumers. API design also plays an important role in API governance.

API governance refers to the comprehensive set of standards, policies and practices that direct how an organization develops, deploys and uses its APIs. Effective API design produces APIs that adhere to these predetermined policies, with robust, up-to-date documentation that explains how the API works. The result is well-designed APIs that have better reusability, scalability, compatibility and provide a better user experience for their end-users.

There are many different API use cases and numerous approaches to API design, with some protocols, architectural styles and languages better suited for specific tasks or use cases than others.

As the use of web APIs has increased, it has led to the development and use of certain protocols, styles, standards and languages. These structures provide users with a set of parameters, or API specifications, that define accepted data types, commands, syntax and more. In effect, these API protocols facilitate standardized information exchange.

Common protocols, architectural styles and languages include:

• SOAP (simple object access protocol)
• Remote procedure call (RPC)
• WebSocket
• REST (representational state transfer)
• GraphQL

Choosing the correct structure for a new API is an important aspect of the design process. These protocols, architectural styles and languages aren’t necessarily better or worse than each other. They are different tools for different tasks.

SOAP is a lightweight XML-based messaging protocol specification that enables endpoints to send and receive data through a range of communication protocols including SMTP (simple mail transfer protocol) and HTTP (hypertext transfer protocol.) SOAP is independent, which allows SOAP APIs to share information between apps or software components running in different environments or written in different languages.

Compared to other kinds of APIs, SOAP APIs tend to be developed in a more formalized, structured way. SOAP APIs have been around since the 1990s; it’s an older, more established format, but also slower than more modern architectures like REST. 

SOAP works by encoding data in the XML format and does not support data transfer in other formats. On the flip side, SOAP APIs don’t necessarily require HTTP to transport messages, which give them more flexibility in moving data. SOAP is considered more secure than some other protocols, making SOAP APIs appropriate in systems that handle sensitive data.

Remote procedure call (RPC) is a protocol that provides the high-level communications paradigm that is used in the operating system. RPC implements a logical client-to-server communications system that is designed specifically for the support of network applications. The RPC protocol enables users to work with remote procedures as if the procedures were local. This makes them well-suited to situations that require many client/server interactions and client/server interaction.

RPC APIs can be further broken down into XML-RPC, JSON-RPC and gRPC. XML-RPC is a remote procedure call that uses a specific XML format to transfer data. They’re older than even SOAP APIs, but simple and lightweight. JSON-RPC is a remote procedure call that uses JSON (JavaScript Object Notation) to transfer data. Because JSON uses universal data structures, it can be used with any programming language. 

gRPC is a high-performance, open source RPC framework that was initially developed by Google. gRPC uses the network protocol HTTP/2 and Protocol Buffers data format and is commonly used to connect services in a microservices architecture.

WebSocket APIs enable bidirectional communication between client and server. This type of API does not require a new connection to be established for each communication—once the connection is established it allows for continuous exchange. This makes Web Socket APIs ideal for real-time communication. 

Live chat, real-time location tracking and data broadcasting are all excellent use cases for WebSocket APIs. WebSocket APIs are also useful for data synchronization, which is the practice of keeping data consistent and up-to-date across several devices or systems, because they can update in real time, without the need to create a new connection each time a change is made.

REST is a set of web API architecture principles. REST APIs—also known as RESTful APIs—are APIs that adhere to certain REST architectural constraints. REST APIs use HTTP methods such as GET, PUT, HEAD and DELETE to interact with resources. REST makes data available as resources, with each resource represented by a unique URI. Clients request a resource by providing its URI. REST APIs are stateless—they do not save client data between requests.

RESTful APIs are popular because they are lightweight, flexible and easy to use. They fully support message transport in different formats—such as plain text, HTML, YAML, XML and JSON—and they also support caching. While this makes them useful in a great variety of contexts, some stations call for a more specific language or protocol to efficiently complete a task.

GraphQL is a query language and API runtime that Meta developed internally in 2012 before it became open source in 2015. GraphQL enables users to make API requests with just a few lines, rather than having to access complex endpoints with many parameters. This capability can make it easier to generate and respond to API queries, particularly more complex or specific requests that target multiple resources.

Given that Meta developed this query language to make their mobile applications more efficient, it makes sense that GraphQL APIs are useful for mobile applications. By offering a single entry point, GraphQL APIs can lower load times by querying data without having to make multiple requests to the server. 

There are four key stages of the design process for an API:

• Plan
• Develop
• Test
• Deploy

All of these steps require collaboration between key API stakeholders. Although some of the steps are best suited to some stakeholders over others, API design should still be collaborative throughout the process. This helps developers avoid adding in extra functions that the program doesn’t need, speeding up the development process overall.

The first step of any project is to get everyone on board with what kind of new API they are creating. A public-facing API intended for customers to interface with in an e-commerce setting has different design and function needs than one that is intended to be used internally for an authentication workflow; it is important that all stakeholders understand the use cases for a potential API before development begins.

Understanding what an enterprise is building (and why) can give developers a better idea of how to build it, including what protocols to use. If, for example, this potential API requires real-time communication, then developers know that they might use WebSocket when making it because that protocol is well suited to that purpose. 

Once the stakeholders have a clear vision of what the API will be and how it functions, it’s time to start building it. Over the process of API development, the developers define the API endpoints; design the data model for the API; make sure that the API adheres to API security policies and returns standard status codes for errors; if necessary, implement authentication mechanisms such as HTTP headers, API keys, OAuth, or JSON Web Tokens (JWT); define error codes, messages and and responses.

Another part of the development process is documentation. While the API is being built, all the choices being made should be captured in a human-readable and machine-readable document. A human-readable document is written in a natural, easy to understand language. A machine-readable document should adhere to an API specification, such as the OpenAPI specification, which standardizes the format so that it’s consistent and able to be integrated into future systems.

API design can be a highly iterative process; especially if the APIs expose sensitive data, it’s important to test them rigorously for bugs and flaws. After building something, it’s important to see whether it works as intended. An important part of testing APIs is mocking, which is the process of creating mock servers with sample data to check whether the API communicates with its endpoints correctly and returns the expected results. 

Mocking can be conducted alongside API testing. API testing includes contract testing, which establishing what a request and response should look like; unit testing, which confirms that a single endpoint delivers the expected response; load testing, which tests if the API is able to perform under peak traffic and end-to-end testing, which validates user journeys that involve communicating with more than one API. Testing can be done manually, or by implementing automated testing frameworks.

If everything is working as intended, then the API is ready to be released and deployed. By this time, it’s important that the API documentation is finalized so that other users and their machines can properly integrate this API into their computer network environment. It’s possible that once the API is released, users find issues with it that the stakeholders didn’t anticipate. It’s helpful to have a versioning strategy in place before the API is released so that if the developers need to update the application it is done so clearly and consistently.

An API-first approach to application development prioritizes designing APIs at the beginning of the software development process and builds applications with services that will be delivered via APIs. The idea is that prioritizing API design early on in software development, the resulting APIs are more reusable, secure, efficient, easier to use and better aligned with the organization's goals. This approach is in opposition to a code-first approach, which puts code logic first, with developers creating APIs to fit into software later. 

API design is key in an API-first approach. In API-first, APIs are central to application development and well-considered design promotes the development of better performing, more valuable applications. 

Strong API design practices can also help improve both the developer experience and the end-user experience by discovering and resolving developmental and performance snags before they escalate into larger issues.

Stakeholders can establish from the beginning of the development process that all the enterprise’s apps integrate and play well with each other. When implemented successfully, an API-first approach with comprehensive documentation enables developers to reuse existing APIs rather than re-creating functions that already exist.

REST (or RESTful) APIs are loose in structure. The only requirement is that they align to the following six REST design principles, also known as architectural constraints: Uniform interface, client/server decoupling, statelessness, cacheability, layered system architecture and, optionally, code on demand. 

These architectural restraints make RESTful APIs well suited to an API-first approach: Client/server decoupling and statelessness are helpful in particular. 

In a RESTful API, client and server applications must be independent of each other. The only information that the client application should know is the uniform resource identifier (URI) of the requested resource; it can't interact with the server application in any other ways. 

RESTful APIs are also stateless, meaning that each request needs to include all the information necessary for processing it. In other words, REST APIs do not require any server-side sessions. These constraints render these APIs independent from an enterprise’s servers, making them flexible—client and server-side applications can be written with different languages and protocols without affecting the API design.

RESTful APIs are also a good fit for an API-first environment because they are scalable and lightweight. The separation between the client and the server improves scalability because RESTful APIs do not need to retain past client request information, reducing communication bottlenecks. Effective caching can also reduce client/server interactions, another plus for scalability. Because RESTful APIs use the HTTP format for message transport, they can accept data transfer in multiple formats. This can simplify integration into new environments.

A microservices architecture is a cloud-native architectural style in which a single application is composed of many loosely coupled and independently deployable smaller components or services. REST APIs are often used to enable communication between these smaller services.

An API-first approach meshes well with microservices architecture schema because APIs are used to connect the services together. If API design is made a priority within an organization and the APIs are designed to seamlessly communicate with each other, developers save time while packaging those services together into larger applications. 

To derive the most value from enterprise APIs, organizations often emphasize:

• API governance and documentation
• Gathering stakeholder feedback
• Proper authentication
• Versioning
• Standardizing error messages
• Scaling and context
• Consistency

These principles help keep all stakeholders informed throughout the API design process and make sure that APIs align with organizational goals and strategy.  

API governance and documentation: Establishing an organization-wide API governance and documentation strategy early on helps promote consistency and make an enterprise’s API portfolio easier to navigate. For example, an organization might choose to adopt a specification such as OpenAPI so that all enterprise APIs adhere to an industry-wide standard. In any case, maintaining proper and consistent governance and documentation enables new API users to gain a quick understanding of the API and its functions. 

Gathering stakeholder feedback: Early input from core stakeholders and API consumers helps keeps developers on the right track throughout the development process. Poor communication can lead to delays in API development and less valuable APIs.

Proper authentication and API security: To protect APIs, as well as sensitive data, organizations implement authentication techniques that provide validation for API requests. Authentication mechanisms such as API keys, OAuth and JSON Web Tokens (JWT) provide different methods of securing data and API traffic. API encryption, the process of encoding data for travel between client and server, is also used to protect data and APIs.

Testing and versioning: API testing includes covering various scenarios, positive and  negative, to identify issues before an API is deployed. APIs evolve over the course of this testing and developers create new versions that fix bugs or improve performance. New API versions are also released for other reasons, such as when developers add new features to an API. Versioning is how developers manage changes to an API, make changes transparent and see to it that updates don’t disrupt current users.

It’s helpful to have versioning mechanisms—such as URL-based versioning or header-based versioning—defined before development begins in earnest. 

Standardizing error messages: Proper error handling improves an API consumer’s experience because it aids in troubleshooting when things go wrong. Error codes, messages and responses need to accurately describe the nature of the error and remain clear and consistent.

Context and constraints: Every API exists in a specific context that determines how it will be built and what its functions are. Competing project deadlines, expected traffic volumes and whether the enterprise is API-first or code-first can shape the resultant API. It’s important for all stakeholders to be aware of this information so they can make informed decisions during the development process.

Consistency: Above all else, keeping everything consistent generally leads to better API design. Consistency in API design is more than just versioning and error codes. When defining endpoints, keeping naming conventions consistent can make them easier to identify. When making a specific request to an API, it should be resolved in the same way every time. When everything is consistent across an API landscape, it’s also easier to document APIs so that they’re understandable for future users.