Web APIs are highly variable things – they can be custom-built, designed around a single purpose, all-encompassing, and almost everything in between. Shifting requirements dictate what the interface is comprised of. Due to this, it’s hard to find commonalities between APIs and their user-facing portals.

That being said, there are some basic requirements that, despite the variability of the API industry, every single API must attain if they are ever to have a userbase.

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.

Today, we’re going to look at these seven basic items, and define exactly what they are, why you need them, and how they add value to the API.

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. Document your authentication method, whatever it may be, and do so completely!

2: HTTP Call Type Definitions

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.

Common call type verbiage that should be defined and discussed are listed below.

• GET: Typically used to retrieve a representation of a resource, GET is going to be one of the most commonly used verbs for most APIs. As such, documentation should delve into exactly what GET is used for in the API, what resources can be called, and what limitations on this functionality are in place.
• POST: Less commonly used by the average user than GET, POST is a method of submit an entity to the resource, and typically results in a change of state. POST is still commonly used, and as such, should be considered secondary in importance to GET, yet treated with the importance it deserves.
• PUT: PUT is essentially a method for updating or replacing an entry. Accordingly, this function will actually be limited to authorized users in most implementations, and as such, may not be applicable for the entire user base. That being said, how PUT functions and what entries are changeable should be well-documented.
• PATCH: Used for updating or modifying an entry, PATCH is going to be similarly limited like PUT, though in some implementations it might be used to modify specific entries that are unique to the user – in this case, documentation for how that is done should differentiate between the two.
• DELETE: Delete is specifically used to delete an entry, and as such, is often heavily limited in its use and requires higher rights to utilize. Accordingly, while the use of DELETE may not be something that should be documented extensively, the limitations of user classes should definitely reference this verbiage and whether or not it is something the average user will have to be concerned with.

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.nordicapis.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.

A great example of this sort of documentation can be found in the Heroku Dev Center. Heroku offers documentation in Node.js, Ruby, Java, PHP, Python, Go, Scala, and Clojure. By offering this wide range of documentation options, they not only cover popular languages, but languages that are more use-limited or for specific types of systems (such as Go, which is typically used for high-concurrency applications that require a relatively simple codebase).

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.

Do note that in some cases, this is less important – for GraphQL, for instance, much of the response is actually defined by the request, and so a general response example is more appropriate. Even then, however, documentation of common error codes, common success notes, and the structure and expected format of such a response is extremely valuable to the end user, and should not be ignored.

Home-Cooking vs API Documentation Solutions. Which is Better?

While the elements discussed above are certainly hard to argue against, how API documentation is generated is actually a hotly debated subject. There are as many methods of documentation generation as there are APIs that might use such methods, and as such, it’s quite hard to give a single recommendation above all others.

That being said, these typically fall within two camps – home-cooked DIY implementations, or documentation solutions, systems that automatically create documentation using a set of criteria. Both have their own unique values and properties, but ultimately, the choice comes down to the specific purpose of documentation.

Home-Cooked Documentation

Home-cooked, or DIY, means developers note functions by hand. Hopefully, this is done deliberately, and with thought as to the editability of such resources moving forward. Popular methods for doing this can range from a simple static website presenting API documentation to a** hypermedia-rich wiki**, allowing for community editing, bug tracking, and more.

While these systems offer unprecedented flexibility and control, and are easily implemented on existing projects, they do require a significant amount of effort and energy to maintain, and often require a team member whose soul purpose on the team is to serve as the documentation manager. For small projects, this is a hard cost to justify.

Automated Systems

For APIs who wish to have a more automated system from documentation to iteration, there are many tools available, like Swagger UI, Slate, Gelato, and more. In a previous post we researched and charted out over 30 API documentation solutions. Many options exist, from hands-on open source tooling to comprehensive developer portals. Many of these libraries and frameworks can be used to generate HTML and CSS to display API methods, parameters, values, requests, responses, code samples, and more.

Read: Ultimate Guide to 30+ API Documentation Solutions

Great DX Requires More Than Effective Documentation

While it’s tempting to consider documentation as an afterthought, the simple fact is that such documentation is likely going to be the first entry point into your API and the systems that drive it for the average user. Accordingly, providing effective documentation should be considered less an afterthought, and more an important, critical piece of data for your average user.

The elements discussed throughout this piece form a foundation for powerful, effective, and positive user interaction. However, just having effective documentation does not guarantee a good user experience or developer community. Other areas for improvement include a testing sandbox, developer support channels, and ensuring high uptime with rigorous internal API testing.

Ultimately, your documentation, as said previously, is a base — the stronger your foundation, the larger the structure can be. A perfect foundation does not create a mansion overnight. In other words, keep perspective on what you’re building, and address these elements as they arise.