APIs enable the sharing and modification of data between independent applications. In other words, APIs help different apps work together, whether it’s a CRM and a CMS, a travel website and an airline data stream, or an embedded YouTube video, APIs make these integrations possible. In most cases we’re talking about REST APIs, the most popular style of API for web applications today.
Any app that seeks to integrate with others needs an API. Unfortunately, it’s not as simple as plugging-and-chugging a pre-built product. API developers have a lot to consider, like security, testing, and today’s topic, the user experience.
Whether you’re part of a team building an API or vetting APIs to enhance your marketing workflow, API design should be at the top of your mind. In this post, we’ll hone in on the “I” in API, the interface. You’ll learn the basics of why API design is important to a successful app integration, and leave with seven key qualities of good API design.
Why Is API Design Important?
API design matters for the same reason that website design or software design matters: Your service needs to be intuitive and seamless to learn and master. Otherwise, people won’t use it. Except, instead of front-end users, APIs are designed for programmers. Therefore, in lieu of the user experience, API design focuses on the developer experience.
Developer experience plays a major role in how successful your API will be. If experienced developers find your tool difficult to use, they’ll either begrudgingly push through while thinking (and maybe blogging) poorly of your service, or they’ll abandon it if it’s not worth the time. Either way, this reduces your application’s reach.
But, if we seek to make developers’ lives easy, our API will establish a strong reputation, which increases the odds that fellow applications integrate with your application and get your service in front of more faces. It’s a win for everyone.
To review: API design affects developer experience, developer experience affects adoption of your API, and adoption affects the success of your integration. It’s all related, and it starts with design. So, what makes a good API design?
REST API Design Best Practices
APIs are like websites — each one looks and acts a little different, but most follow a set of baseline design practices that keep them intuitive. When an experienced developer takes on a new API, they shouldn’t have to re-learn everything they know. Overall, things should seem familiar.
To achieve this familiarity and provide the best possible developer experience, here are seven design principles that APIs can follow:
1. Follow REST principles.
For an API to be considered RESTful, it must follow the five required principles of REST. You can learn about these more in-depth in our guide to REST APIs. Briefly, they are:
All interactions with the API must consist of a request sent to the API from the client, followed by a response sent to the client from the API. Clients initiate all interactions.
All requests to and responses from an API must be formatted the same way, in the same language, and under the same protocol. Most rest APIs use the HTTP protocol, which lets clients make HTTP requests to APIs. The most common HTTP requests used with REST APIs are:
GET — for retrieving items from a database.
POST — for uploading items to a database.
PUT — for modifying items on a database.
DELETE — for, you guessed it, deleting items from a database.
All calls to the API are independent of any calls that came before. Each request and response contains everything necessary to complete the interaction, and servers do not store the contents of previous calls.
Requests and responses between the client and the target server should always be processed the same way, irrespective of the number of additional servers (or layers) between them. Layers should not affect the contents of messages either.
Responses from APIs must indicate whether the resource provided may be cached by the client and for how long.
These rules ensure flexibility, compatibility, and security as the API and its respective application grow in resources and capabilities. As long as the API and the client implement these REST principles, the two can be synced.
2. Take security seriously.
Few things damage an API’s reputation more than a successful security breach, which explains why this item is so high on the list. APIs often access and send highly sensitive data, making them a high-stakes tech endeavor for companies. You’re introducing another access point to your data, and it needs to be treated as such.
Therefore, a well-designed API is built with security measures from the start. Below are a few high-level security principles for APIs — read our guide to API security best practices for more detail.
Authentication validates a client’s connection to the API. To preserve stateless transfer, each call to a REST API must be individually authenticated, even if the client has connected previously. Authentication is typically done with credentials included in the request body in the form of a unique access code that the server validates.
With regard to developer experience, the authentication process, while necessary, should not impede developers. Good APIs make it simple to acquire access credentials and connect safely. Some may require users to register with the service and state their intentions with the API.
Authorization follows authentication — after checking that a client connection is valid, permissions must be assigned in order to limit what the client can do and what resources they may access.
To prevent sensitive information from falling into the wrong hands, well-designed APIs employ the principle of least privilege. According to this principle, those who access a service should only be allowed to access the features for which they’re authorized. This might require creating user segments and assigning different permissions to each one. You can have a segment for common third-party clients, and segments for high-level and low-level admins, for example.
A safe API encrypts its client-server connections. Encryption prevents sensitive data from being intercepted, and it’s an absolute necessity for any website or API that cares about reputation. If a user attempts to access your API on public WIFI, non-encrypted data can be snatched by a bad actor, and you’re partially to blame.
At the very least, all APIs should encrypt data transfers with TLS/SSL. This is the same technology used to secure connections between websites and visitors — it’s what provides the “S” in “HTTPS.” Basic encryption is cheap, effective, and easy to set up. There’s no excuse to skip it.
3. Use clear syntax for resources, collections, and path names.
A resource is an item on a server that can be accessed via the server’s API. These are the things that can be retrieved, placed, modified, and/or removed via API requests. For example, video, channel, and comment are all resources in YouTube’s API. Multiple related resources can be grouped under a collection, like channels or a playlist of videos.
Similar to how text and elements of a graphical user interface should signal their purpose, the labels you assign your server resources and collections are key for helping developers understand your internals.
With REST APIs, clients access resources and collections with a uniform resource locator (URL), also called an endpoint. Clients need to write these URLs out, so it’s important that all items are labeled logically.
There are no hard rules for naming resources. But, to help clients fetch resources quickly, many APIs stick to these practices:
Endpoint URLs should be as short as possible and minimize the amount of nesting to reach a particular resource.
Use singular nouns to name resources, and plural nouns to name collections whenever it makes sense to.
Avoid using verbs in pathnames, as this is redundant. The HTTP request verb (GET, DELETE, etc.) should be sufficient to convey the action being taken.
Use consistent language when referring to different instances of the same resource type. For example, don’t use both “article” and “post” as the name for a blog article resource type. YouTube always refers to every video resource as a video, never a “movie.”
In general, use simple and clear language. Avoid overly technical jargon.
For resources contained within other resources or collections, structure URL such that the child resource is appended to the parent resource. For instance:
A GET request to this endpoint would fetch all the comments from a particular video in a playlist. How exactly you structure nested resources will differ by API, but for consistency it’s a good idea to have your endpoint URLs reflect the structure of your database.
4. Error messages should be useful.
No matter how simple and intuitive you make your API, things are bound to go wrong on the client end. They might have formatted their request incorrectly, failed the authentication process, or requested a resource that doesn’t exist.
In all cases, both successful and unsuccessful, a REST API should return the appropriate HTTP response status code. In the case of errors, additional information as to why the error occurred will curb at least some frustration in the face of unexpected problems.
One more important note about messages: Be conservative with error message feedback. Omit information that you believe could be exploited by unauthorized hackers to access your data.
5. Enable filtering.
Another way to enhance the developer experience is by offering a way to sort and filter data through the API. Many APIs allow users to place parameters in API requests which affect what resources are returned. Otherwise, it can be difficult for developers, especially those new to your service, to locate what they want in your database.
Plus, if a developer accidentally requests a large volume of data, this can impact server performance. Filtering reduces the chance of this occurring.
6. Update versioning.
As you introduce changes and new features to the API, always include the version of the API being used in the API path. For example:
This gives client applications time to switch over to your newest update — developers can stick with the older version until you decide to phase it out. Like any software, your API will never be finished, so make it easier for developers to adapt as you update.
7. Take care with documentation.
This may be the final item here, but documentation is likely the first place users will go to learn your API, resolve an issue, and track updates. Good documentation is a developer’s best friend, so check out our guide to reading and writing API documentation for more advice on reading and writing it.
Importantly, always make your API documentation freely available. Documentation behind a login or paywall is just one more barrier to access that takes time and may discourage applications from integrating with your service in the first place.
Designing for Developers
Let’s be honest — if you’re not a developer by trade, reviewing API design practices can get a bit dry. All the new terminology certainly doesn’t help.
However, if you’re working with APIs in any way — such as marketing an integration, looking for new software to aid your process, or writing documentation — it’s important to understand what separates great APIs from lazy ones. The quality of your integrations is at stake.
Ultimately, APIs are interfaces, and all interfaces must be created with the end-user in mind. By considering not just users but developers too, you’ll see increased adoption of your product by third-party services and a stronger reputation in your space.
Originally published Jan 20, 2021 7:00:00 AM, updated January 20 2021