I develop different sorts of software and frequently attend hackathons and tech events in Brazil. During this activities, I usually need to learn a new API to perform some task. However, in most cases, I end up with a lack of information needed to use the API documentation properly. It is actually important to note that only a good documentation does not make an API successful but other factors must be considered.”
1. Samples all over the place
Many developers prefer to go straight to the code samples and spend little or no time at all studying and learning concepts. This is one of the reasons why it is important to always provide several samples of API usage, which means that we need to go beyond the basic “Hello, World”. A good tip is to provide at least one sample for each API important feature. It is also worth to provide samples in each of the major languages/environments in which the API will be used and highlight how it would behaves in certain situations (bad or no Internet connection, usage limit exceeded etc). It is also worth remembering that the more didactic, objective and realistic those samples may be — and similar to use cases popular in the market — more suitable the samples will be.
2. Have a test environment
The developer who is starting to use an API will make several tests before putting it into use officially (in production). Because of this behavior, it does makes sense that an API should be used in a test or evaluation environment because then it is possible to “play” and find out what you can be able to do using it. In some cases, especially in APIs that involve the use of monetary values, it is worth investing in trial versions with some type of limited usage by time or feature.
Some APIs require several steps to be used, such as registration, authorization, and token validation. These important steps may discourage some developers to perform a quick test. For these cases, it is recommended to create a “playground” or a ready environment where the developer can get a taste of how the API works without having to go through various environment configuration steps and obtain authorization and authentication features.
3. Documentation beyond the basics
Documentation is a required feature for those who produce an API. There are several types of documentation, but what I search for when I’m learning is something that goes beyond a simple “JavaDoc” or something generated automatically. I look foward particularly for diagrams, architectures and some kind of visual information that helps me to understand the prerequisites, the workflow, the features and the necessary details so that I can do the job using the API. “Getting Started” guidelines are also great starting points for those who access the API website for the first time and have no idea of “where and how” to start using it.
Among the important items of a good documentation is to make clear where the API can and should be used and where it makes sense using it. This is important [for the developer] to know how far it is possible to go with it and what are the scenarios and use cases where it is NOT recommended as well. It is also very useful to highlight the updated list of bugs for each version of the API, for there is nothing more frustrating than wasting so much time trying to discover a bug after it has been fixed in a newer version of API.
4. A good FAQ and RTFM
I love FAQs (Frequently Asked Questions) when I am learning how to use an API. This format of quick questions and answers helps me a lot to understand the purpose and use of the API features. Not to mention that this way it is easy to find out what other people are trying to do with the API.
However, it is NOT worth to include old or outdated information that do not make sense anymore with obsolete technologies. It is also important to adopt a lighter tone, humorous and didactic when writing the FAQ — regarding the official documentation — as a more friendly content encourages developers to work with the API. On the other hand, try to avoid sarcasm, or treat the developer as “stupid” or the silly “read the manual”, indicating the polite “RTFM”. So try to be gentle.
5. Build up a communication channel
A successful API should have some sort of communication channel with the developer. This channel may be an email, Twitter, contact form or any other thing that allows the developer with a technical question to be heard. I emphasize that by indicating the average response time in asynchronous communications (such as an email) helps a lot to have that feeling that the “client” is important and will be heard.
In general, the communication channels for developers should be more simple, short and quick, because whom creates software and goes so far as to contact the developer probably has done several tests and found a barrier that made stand still and call for help. Therefore, communication should be direct and right to the point so that the development is not further delayed.
6. Make it clear prices, type of access and use limitations
Many APIs rely on a business model that charge for use, according to some kind of list of features, time or number of calls. It is extremely important to make clear what are the values, types of usage (free package, normal or advanced), payment and collection modes, and also how the refund of values works. It is common that APIs are initially free and then reach a certain number of users to become paid. At first, such a business model change can frustrate and scare some developers. In this case, what you want to hear is a clear communication of how things will be once the service becomes payable, including periods, limitations, advantages and disadvantages of how the API service was and how it will be in the new business model.
7. Keep a decent history
Every software project that changes every new version has a history behind. That history is important to show not only the project steps, but also to make it clear which direction it is taking. Several APIs are constantly changing according to the environment, for instance, new browser versions, features to make it faster, changes to support new platforms and general adaptations to new technologies and web development trends. Therefore, knowing how to indicate historical properly is important to provide a context and make clear the reasons why the API is presented today.
8. Have a troubleshooting guide
It is very common to find problems and difficulties when studying a new API or when certain environmental conditions may change. At such times, it is important to have a troubleshooting guide that will indicate, step by step, what are the points to be observed.
In the case of APIs, one troubleshooting guide should tell step by step how to perform a connection test, which parameters are required, what kind of return is filed for each request and what to do if any of the steps fail. This type of guide is very useful when debugging a problem and it is not known which of the solution components is failing. In this situation, a diagnostic guide and step by step instructions are extremely useful in helping to first understand what is going on and then taking some action to remedy the problem.
9. Roadmap and new features
One factor developers takes into account when studying and pondering whether it is worth or not to use an API is its continuity. In other words, ask yourself: is it worth to study, invest time and change an application to use the API if it won’t serve me in the future? In other words, no one wants to use a service that looks like an old western town abandoned; so a good way to make clear the API project goes is to provide a roadmap in a chart showing the latest API versions and the planning for the next versions. Thus, the API developer shows its commitment to maintain the service in the future and makes it clear that the project is serious and not just something temporary with an uncertain future.
10. Highlight main projects using the API
An API is typically part of a larger software even if this software is just a graphical interface for your use. If the design of an API was well planned and it is something really useful and flexible, it is normal to expect different types of projects making use of it. Highlight and emphasize different projects using the API is a great way to encourage people to use it too and value the service. When I am evaluating an API and I see several projects using it, I have a sense of confidence because if someone is already using this service in some way, it motivates me to use it as well.
11. Foster the community
No one wants to be that guest who arrives at the party first and realize later that it was the one who showed up. This means that foster a community is a very important step for developers using the API so they do not feel isolated and lonely.
There are several ways to deal with the community, including events like hackathons, programming dojos, meetings where people get along to translate other programming languages or produce documentation, or even social events where community members go out to take some drinks and talk about the project.
fRegardless the meeting format, it is worth investing in the user community so that will be possbile to improve the service, hear how it is used and get in touch with someone that rely on the service.