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