How to Make Your APIs More Developer-Friendly

Claudiu
Claudiu
bits and pieces of documentation & marketing 👨‍💻

In this article, we'll teach you how to make developer friendly APIs.

You’ve put a lot of resources and time into creating your APIs, but the developers seem hesitant to use them.

Why could that be?

There are a number of reasons, and one of them is that your APIs might just not be as developer-friendly as you think they are.

Luckily, you can salvage the situation, and in this article, we’ll show you how to take your API documentation to the next level.

Let’s get started!

Know Your Developers

If you want to create developer-friendly APIs, you should know your developers.

That isn’t a groundbreaking statement by any means, but it very simply describes an unavoidable part of the process.

If you start thinking of APIs as your product and developers as your customers, it's easy to understand why you should make an effort to understand your developers.

A good salesperson knows their target audience, what they want from a product, what they like, and how to offer them a product that meets their needs.

Furthermore, software developers aren’t one homogeneous group, as Mike Kelly, product designer and software engineer, points out:

In reality, there are innumerable forms of developers, each with their own set of constraints and requirements.

Developers have different skill sets and levels of knowledge, come from various industries, and work with different technologies—to name just a few factors you should consider.

And according to Christina Voskoglu from SlashNation, the 19th Developers Economics Survey showed that nearly 90% of developers use APIs.

graphic representation with 90% of developers use APIs
Illustration: Archbee.com / Data: Nordic APIs + SlashData

That means that the majority of the millions of developers in the world use APIs, and it’s unlikely that you can make a one-size-fits-all solution to cover all of their needs.

So, what can you do? You can focus on the developers who actually use your APIs.

A helpful method can be to employ a well-known marketing practice of creating personas.

Here’s how Janitra Ariena Sekaputri, an experienced data analyst, defines personas:

Janitra Ariena Sekaputri, experienc as data analyst
Illustration: Archbee.com / Data: Medium

In other words, you can collect the data you have about users of your APIs, like their technological preferences, industry background, demographic information, etc., and create a fictional user with those characteristics.

How many personas you’ll create depends on the variety of developers using your APIs.

However, you should end up with something like this:

Developer Personas from Figma
Source: Figma

You can see the skills “Kyle Matthews” has, what he uses for personal development, his preferred products, how he works, etc.

When you have all the relevant information about a group of users in front of you like this, that can significantly help you adjust your APIs to make them more accessible to your developers.

Have Detailed API Documentation

When developers decide to use your APIs, they often go straight to your API documentation.

That’s perfectly reasonable. Even experienced developers need to learn about software interfaces before using them efficiently.

Documentation should provide developers with everything they need to know to get started with APIs, from the basic information and tutorials to the lists of requests and responses, endpoints, etc.

That way, developers won’t waste time looking for the best ways to use your APIs or miss out on their full potential.

As we’ve mentioned, detailed documentation should provide developers with the basics first, so a “Getting started” section is a must-have.

SendGrid has a section like that in their API documentation. It provides an overview of APIs, including instructions on how to send an email with SendGrid API.

Send email using the API
Source: SendGrid

As you can see, the instructions are straightforward and clear but also detailed.

Developers are immediately warned that they need to have an API key, and they then get a code snippet that they can copy, along with step-by-step instructions for the rest of the process.

That’s a precise and concise tutorial on how to get started, and you can find the same attention to detail in the rest of SendGrid’s API documentation.

For example, if you want to learn how to filter all messages, you get specific instructions with queries on the left-hand side and code in multiple programming languages on the right-hand side.

How to filter all messages
Source: SendGrid

That way, the developers get the information about the possibility of filtering all messages, as well as all the necessary information they can immediately use to try out that functionality.

For creating and publishing detailed API documentation, you should have an excellent tool. Luckily, our own solution, Archbee, can meet all your needs.

You can create a comprehensive quick start guide, like the one by Breadwinner you can see below, and enrich it with screenshots and other visuals to make it easier to follow.

Quick Start Guide on Breadwinner
Source: Breadwinner

Of course, you can’t have detailed API documentation without code samples.

With Archbee, you can create code samples in the most popular programming languages and insert them directly into the documentation.

API Overview on Breadwinner
Source: Breadwinner

To sum up, API documentation is crucial for your users.

The more guidance they get from your documentation, the easier it is for them to use your APIs.

If you want to make them developer-friendly, document them in as much detail as possible.

Focus On Ease of Adoption

Developers have a lot on their plate during their workday, so they appreciate anything that can save them time and effort.

In addition to writing code, testing it, dealing with bugs, communicating with clients, collaborating with other members of the team, attending meetings, and many other responsibilities, spending hours trying to figure out APIs is something they understandably aren’t eager to do.

However, if you make your APIs so accessible that they can get them up and running in little time, they’ll most likely gladly use them. Here's a read recommendation: Why Developers Are Not Using Your APIs.

Developers already rely on APIs a great deal in their work.

According to the 2022 State of APIs report, 62% of them relied more on APIs than the year before, and 69% expect to rely on APIs even more in 2023.

Graphic representation of 62% of people who relied more on APIs
Illustration: Archbee.com / Data: State of APIs

So, why not make it easier for developers to adopt your APIs?

The first thing you can do is make the signing-up process simple.

For instance, the National Park Service API provides data developers can use in their apps, maps, and websites.

You need an API key to access their API, but it’s very easy to get it—just provide the name and email address.

Get Started with the NPS API
Source: NPS

In addition to a simple sign-up, developer-friendly APIs should have language-specific libraries.

Of course, you can’t provide libraries for every programming language under the sun, but there should be resources for at least the most popular ones.

For example, Plaid has libraries for five programming languages.

Plaid has libraries for five programming languages
Source: Plaid

That way, developers can choose their preferred language, making it easier for them to adopt your APIs.

And what about when things don’t go as planned for a developer while using your APIs? You should have a solution for that and provide them with quality support.

Regardless of the problem that might occur, developers should know that they have the resources to troubleshoot the issue.

That’s why Giphy has a FAQ section for their APIs.

Giphy FAQ section
Source: Giphy

It covers the most common questions that developers might have so they can quickly find an answer.

If the problem isn’t covered in the FAQ section, developers can always contact Giphy customer service for help.

That kind of support makes API adoption easier, which is precisely what you want in order to encourage developers to rely on them.

Follow API Naming Conventions

Although naming APIs can seem like a simple task, there are conventions you should follow to make the developers’ work easier.

Naming an API is important because developers often rely on the name to assess what kind of information they’ll deal with. Here's a better view at the importance of writing thorough API documentation.

Therefore, naming should make things clear and minimize the chances of confusion.

If it’s not done right, it could mislead the developers, causing them to waste time and effort, ultimately building frustration.

And frustrating your users won’t make them want to use your APIs more.

That’s why there are some established naming conventions you should follow.

For example, take a look at the Google Maps request below.

Google Maps request
Source: Google

That request features some of the API naming conventions that are advisable to use.

One of them is to use pluralized nouns instead of verbs to specify the resource.

In the example above, Google used “directions” instead of “getDirections”, “createDirections” or some other combination of verb and noun.

Another convention is to use forward slashes for hierarchy but to omit one at the end.

Use forward slashes for hierarchy
Source: Google

Above is a good example from Google of using forward slashes between individual elements.

On the other hand, software engineer Nadin Pethyagoda shows a name ending in a forward slash as an example of what not to do, which you can see below.

REST API Naming Conventions and Best Practices
Source: Medium

Among useful naming conventions is also letting your users know what version of the API they’re using.

Take a look at how Etsy does that:

How Etsy use API
Source: Etsy

That way, users can clearly see that they’re using version three.

These are just some naming conventions you can use to make your APIs more user-friendly.

There are also important ones like:

  • Use American English
  • Use proper grammar
  • Avoid jargon
  • Make names simple and intuitive

‍

Relying on naming conventions like those will make your APIs feel familiar to your users right from the start.

Include Descriptive Error Codes

Sooner or later, an API error code will show up. When that happens, it’s essential that its content is clearly understandable to the developer.

That’s because error codes help a developer diagnose and fix the error. If they don’t convey enough, they can also make the process lengthy and tedious.

It all depends on the content of the message.

So, what should a great error code do? Here’s Kristopher Sandoval, a web developer and author, with his take:

Kristopher Sandoval quote about quality errors code
Illustration: Archbee.com / Data: Nordic APIs

In other words, an error code should be descriptive, providing a developer with the necessary information about the problem and its cause.

If the error code is not like that, it’s unhelpful, as it only partially conveys information about the issue.

For example, take a look at the error message below.

400 error message on pctechguide
Source: pctechguide

What can a developer learn from it?

Not much, apart from the fact that the server can’t process a request and that the problem occurred on the client side (because it’s in the 4xx range).

On the other hand, there’s an error message like this:

400 error message on Mozilla
Source: Mozilla

Here we have more information.

In addition to the information that the error is on the client’s side, we know there is a problem with the request header or cookie.

From here, there are possible solutions, like clearing the cache and removing the cookies for a problematic website.

Let’s look at another example of a helpful error message, this time from Twitter.

helpful error message on Twitter
Source: Twitter

Here we have a code number and a description of the error.

We can already see from the description that there’s a problem with authentication data.

However, what’s even more helpful is the code number, which we can look up in Twitter’s API documentation, and we’ll know in detail why the error occurred.

Bad authentication data
Source: Twitter

We now know that either we didn’t present any authentication data or it was invalid.

The point is that the error messages don’t need to be the length of a short story to be helpful.

Even brief messages can be descriptive enough to put a developer on the right path to fixing it—often, that will be more than enough.

Conclusion

As we’ve discussed in this article, there are various ways to make your APIs developer-friendly.

You can make an effort to get to know your developers and understand their needs. Also, having comprehensive API documentation goes a long way in making APIs more accessible.

Ease of adoption is another important factor because many developers won’t have the patience or time for complicated APIs.

Furthermore, following API naming conventions and providing descriptive error codes can make your APIs significantly easier to use.

All those methods are undeniably useful—try them out, and the results will come.

See how easy it is to use APIs in your documentation with Archbee with our free 14-day trial.

‍

FAQ

Frequently Asked Questions

Why is it important to know your developers when creating APIs?
Expand FAQ

In order to make your APIs more developer friendly you should have the next checklist: know your developers, have detailed API documentation, focus on ease of adoption, follow API naming conventions, include descriptive error codes. Those are just a few of the things you should consider to make your APIs better!

Knowing your developers is crucial as it allows you to understand their needs, preferences and constraints, and therefore create APIs that are more tailored to their requirements. Developers are a diverse group with different skill sets and levels of knowledge, from various industries, working with different technologies. Focusing on the developers who actually use your APIs can considerably help in making your APIs more accessible.
What does a good API documentation provide?
Expand Button

To create detailed API documentation, define your audience, determine the documentation structure, describe the API and its endpoints, provide examples, explain error codes and responses, include SDKs and sample code, provide testing instructions, and update the documentation regularly.

A good API documentation provides developers with everything they need to know to get started with APIs, from the basic information and tutorials to the lists of requests, responses, endpoints, etc. It should also contain useful sections like 'Getting started' and provide detailed and clear instructions. It should not make the developers waste time looking for the best ways to use your APIs or miss out on their full potential.
How does ease of adoption contribute to making APIs developer-friendly?
Expand Button
Ease of adoption is vital for making APIs developer-friendly because developers often have a lot on their plate and they appreciate anything that can save them time and effort. Making APIs so accessible that they can get it up and running in little time encourages developers to utilize them. It involves making the signup process simple, providing language-specific libraries, offering quality support and resources for troubleshooting.
What is the importance of following API naming conventions?
Expand Button
Following API naming conventions is important because it makes the developers’ work easier. Naming an API allows developers to assess what kind of information they’ll deal with. Therefore, naming should make things clear and prevent confusion. If not done appropriately, it could mislead the developers, causing them to waste time and effort, and lead to frustration.
Why should an API include descriptive error codes?
Expand Button
Including descriptive error codes in an API is vital as they help a developer diagnose and fix the error. The content of the message should be clearly understandable, providing a developer with necessary information about the problem and its cause. A good error code is helpful as it puts a developer on the right path to fixing the problem, making the process less lengthy and tedious.

đź“– Table of contents

Answer questions instantly

Create and share documentation that answers questions instantly with Gen AI

Discover Archbee

Receive documentation and technical writing tips & trends — our newsletter

Join 5000+ people from around the world that receive a monthly edition of the Archbee Blog Newsletter.

Read more in

Documentation