7 Signs of Good API Design That Marketers Should Know

Without application programming interfaces (APIs) the vast technical ecosystem of web services wouldn’t exist as it does today. And without good API design, your service or product wouldn’t be as intuitive or effective as it can be.

API developers have a lot to consider, like security, testing, and today’s topic: user experience. Navigating the world of API design best practices can seem daunting, but keep delighting the developer — and customer — central to everything and you can’t go wrong.

Whether you’re part of a team that is 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 essential to successful app integration, and leave with eight key qualities of good API design.

What is API design?

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. That’s why learning how to design an API is so valuable.

API Design

The term API design refers to the sum of the architectural and planning decisions you will make when creating your API. Good API design is essential because it impacts how useable and intuitive your integration is. And that directly impacts how likely developers are to use it. It’s also during the API design process that you’ll determine the scope of your integration.

What is an example of good API design? Consider some of the APIs you use in everyday life.

For instance, your weather app has an API that integrates geographical data from Google Maps and allows the application to get a sense of where you are. This seamless user experience is in part because the integration takes into account API design best practices.

How to Design an API

Creating an integration that incorporates API design best practices is multifaceted. As a result, those wondering how to design an API will find that the most attainable way to do so is by following REST principles (if that’s the categorization of API you are targeting). Don’t worry —we’ve rounded up a few of the most important REST principles good API design adheres to in this article. Or, you can learn more here.

Why is good 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. APIs are designed for programmers. Therefore, in lieu of the user experience, API design focuses on the developer experience. Good API design is created with this in mind.

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. Implementing API design best practices will ensure this does not occur.

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 it. Ultimately, good API design can make the difference between your service getting in front of the right people or not. Creating APIs that adhere to best practices is a win for everyone — your company, other developers, and ultimately, the customer who will benefit from the use of the integration.

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?

What are the 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. Of course, good API design has a role to play in this.

To achieve this familiarity and provide the best possible developer experience, here are eight design principles that APIs can follow:

1. Follow REST principles.

Good API design adheres to REST principles which therefore makes it accessible for developers. 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:

Client-Server Separation

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.

Uniform Interface

All requests to and responses from an API must be formatted the same way, in the same language, and under the same protocol. This is a key principle of good API design as influences how instinctual using the integration is for developers. 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.

The API sends its responses in the JavaScript Object Notation (JSON) format, which is easy for client applications to parse.

Stateless Transfer

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.

Layer Independence

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.

Caching

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 good API design and these REST principles, the two can be synced.

2. Take security seriously.

Few things damage an API’s reputation more than a 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

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 API design makes it simple to acquire access credentials and connect safely. Some integrations may require users to register with the service and state their intentions with the API.

Authorization

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. This is one of the most crucial API design best practices because, without it, your API’s reputation can be significantly tarnished.

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.

Encryption

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. Any good API design example includes it, and there’s really no excuse to skip it.

3. Use clear syntax for resources, collections, and path names.

Integrations that implement API design best practices will utilize clear syntax for resources, collections, and path names. This is because syntax dictates the API’s abilities.

To review briefly, 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.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.

Avoid verbs and stick with nouns.

You already know that, when adhering to REST API design best practices, it’s essential to keep things simple and intuitive. A major part of that is avoiding verbs and using nouns when creating your base URLs. It’s considered to be bad practice, and there’s a reason.

Verbs are redundant, and can quickly become confusing for developers looking to use your integration. Instead, avoid using verbs in pathnames and stick with nouns. The HTTP request verb (GET, DELETE, etc.) should be sufficient to convey the action being taken. If you’re finding that the HTTP request verb does not adequately describe the action, consider that your API likely requires additional attention to become easier to navigate.

4. Make error messages 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 facet of good API design that can enhance the developer experience is 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.

Necessary Components for Successful Filtering

API design best practices indicate that enabling filtering is essential, but that’s not all you need to know about the topic. Keep in mind that filters should have three components to make them the most successful they can be. These include:

• Property or field name
• Filter’s value
• Operator

6. Note the version of the API.

As you introduce changes and new features to the API, always include the version of the API being used in the API path.

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. Provide excellent documentation.

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.

8. Add a pagination mechanism.

There’s a reason why it’s considered one of the API design best practices to include a pagination mechanism in your integration. For one, adding API pagination ensures that the integration will smoothly and effectively navigate large amounts of data in the backend.

Pagination mechanisms are also helpful for those who are working with a significant number of endpoints. Deciding to include a pagination mechanism in your API could make the difference between a product that is able to operate at peak performance and one that’s clunky and slower to catch on.

Good API design is beneficial 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 complex 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. And remember: the more intuitive your API, the more likely it will be that developers will harness its power. And, yes, that means your software will have more reach.

Ultimately, APIs are interfaces, and all interfaces must be created with the end-user in mind. By considering not just users but developers and implementing API design best practices too, you’ll see increased adoption of your product by third-party services and a stronger reputation in your space.

Editor's note: This post was originally published in January 2021 and has been updated for comprehensiveness.