Intro
Regardless of the API’s function or purpose, there are seven basic essentials every web API should have in its documentation. Failing to include any of these features could have drastically negative effects on adoption, understanding, and usability.
1: An Authentication Scheme
Authentication, simply put, is proving that you are who you say you are. This is often confused with authorization, or the act of proving you are allowed to do what you’re requesting, but ultimately, authentication is a means of “logging in” to the interface. Authentication is key to many systems that handle rights management.
That’s not to say your authentication system has to be particularly robust or complex, either – there’s a wide range of authentication mechanisms. As an example, HTTP Basic Authentication is perhaps one of the easiest methods to implement in an API. Enforcing access control utilizing this method simply incorporates an Authorization Header into each request, and passes a username and password combination to the authenticating system to prove the user is who they say they are.
Using something like a JWT, or JSON Web Token, can provide not only authentication, but a secure signature that is often passed as an entirely encoded package. This package can then easily be encrypted using something like JOSE, or the JSON Object Signing and Encryption library, to create a secure methodology.
There are a number of methods for authentication ranging from simple to complex, each with their own methodologies, eccentricities, and caveats.
Failure to document your authentication method in a clear and plain manner will not only make discovery of API function that much more difficult, it can also result in first time users opting not to use the API at all, eliminating your early user base.
Do it!
Document your authentication method, whatever it may be, and do so completely!
2: HTTP Call Type Definitions
(GET - POST - PUT - DELETE)
Perhaps just as fundamental as noting your chosen authentication scheme is the documentation behind the various HTTP call types. Any web API will interact with the various HTTP call methods, and as such, documenting which methods are used and how they are used within your API is going to be extremely important.
3: Endpoint Definitions
Everything that has been documented, of course, is entirely useless without explaining the specific endpoints that will be utilized. Endpoints are named somewhat humorously, considering they are the beginning of a user’s interaction with your internal system – accordingly, they should be documented with appropriate weight.
As an example, let’s assume we have an endpoint like https://api.example.com/v1/. What specifically does that endpoint do? By just stating it exists, we’ve done almost nothing – we’ve not discussed what the endpoint does, what its limitations are, if it has any partner or sister endpoints that can be used as an alternate channel, or even if that endpoint is restricted to specific users.
The first way we can begin to add value to this endpoint definition is to explain specifically what it does,and how it relates to other endpoints. Creating a map of endpoints, and explaining their function and form within the greater API itself is key to this documentation element. Not only will it help your user understand the system at a greater level, in theory, it can also help generally in development by allowing you to contextualize the holistic function of the system as a whole from both the developer and the user point of view.
4: URI Structures, Methods, and Parameters
To further add value to this endpoint definition, we must document the structure and methods for each URI within the API. This should be done to such a deep level that the average user should have all functions available to them described, in detail, so as to facilitate usage. That being said, not everything about an endpoint can or should be documented – especially if the average user does not have the rights that might be required in order to use them.
For example, it is not uncommon to have APIs segmented into two general groups – a free (or even time-limited) version of the API, and one that is strictly for business-to-business or monetized users. In this case, there may be functions in the API reserved to a small subset of users. Documentation of such an endpoint should only be provided to the user who has the authorization to use it. Exposure of information to the wrong parties could result in exploits or attacks.
When it comes to functional documentation, what is often missed is the fact that developers will be discovering the API bit by bit, as functions are discovered or required. This creates a dichotomy where the provider sees a function as obvious, but the developer user may see it as obfuscated – to this end, the API host should document not only the methods of their URIs, but the parameters they might accept. These methods and parameters should be well-documented, explaining exactly what they each do and how they do what they do, limited only by what the developer thinks the user should have access to for security reasons.
5: Human Readable Method Descriptions
The idea of including human readable descriptions is less a technical point and more a human-centric one. While the data we’ve suggested above is indeed chiefly important, not every user of your API will be able to understand them in their plain form. Because of this, adopting your machine-readable documentation into personalized, human readable systems is extremely important.
This, in fact, presents an opportunity to re-evaluate what the purpose of our documentation actually is. So far, we’ve only discussed documentation in terms of what the technical end-user is going to need.
While this is fine in general terms, it does miss the fact that not all users are going to be highly-technical – as such, we must consider documentation as less a “technical playbook”, and more a “tome of understanding.” Defining your methods and documentation entities in human terms is extremely important as an adjunct to more technical documentation.
6: Requests and Examples
Knowing a URI structure is important, yes, but ultimately, without an idea of what the URI request itself looks like in practice, this documentation is utterly incomplete. Accordingly, a series of examples of what an effective request looks like serves a few key purposes.
First and foremost, it acts as an endcap for the rest of your technical documentation; showcasing example API calls turn technical data into actionable information.
Secondly, this serves as a key method for user onboarding. No amount of data is useful without being able to put it into practice, and while most users will understand simple requests, detailed and complex requests deserve their own sort of quasi-tutorial. Accordingly, this can serve that function quite well.
Finally, providing examples can help in the error resolution process, as users can look at their failed requests and compare them with what the request should be. This will help them identify issues in their requests and their general approach, allowing them to solve their problem with minimal dependence on API support channels. It should also be noted that example requests should ideally showcase a variety of supported languages.
7: Expected Responses
An often overlooked element of API documentation, expected response documentation is extremely important. When a user makes a request, the response, even if successful, can often be wrapped in a number of functions, a language-specific package, or another sort of data wrapper. This can make actual API responses hard to decipher. Being able to expect a given response, in a given language, and with a given format is extremely important.
Great documentation examples
Many popular services have excelent API documentation available. That might even be one of the key reason why they are so popular.
Good examples are available from Online payment processor Stripe, development platform GitHub and social media site Twitter.
Further reading