REST API Documentation – Part 1

Just as REST suffers from lack of standards, the same thing could be said about documentation tools that are available to support REST.

Despite the emerging popularity of REST API's, they have suffered from lack of standards-based documentation tools for a very long time.

API documentation is important for the following reasons:

• An API that is properly documented improves the experience for developers and drives developer adoption.
• At times having the right kind of document can decide the life of an API.
• Documentation has moved from just being static and has started providing a live API experience.
• The most important piece of user experience for a developer who consumes an API is the developer documentation.
• Any product, if its capabilities are not clear for the consumers of the API, will find it hard to succeed.

A 2013 survey by Programmable Web found that REST is the most widely used technology, and complete, accurate documentation was rated as the most important factor in building an API.

Despite the need for having the right kind of documentation, it has mostly been given as an after thought. Also, for a very long time there was a lack of consistent standard-based tooling to support REST based documentation. However, new sets of tools are slowly emerging.

I have been building REST APIs for a long time. Listed below are some of the most important aspects of documentation that users of the API are interested in.

I have gathered most of them from my personal experience of working with a divergent set of consumers who have varying degrees of skill sets when it comes to consuming the API.  

Again, these apply both to APIs built for internal consumption within an organization, as well as external consumers. Here are few items I would recommend:

Business Context

Providing just an API with bunch of example requests and responses is hardly useful. APIs should provide enough business context around the functionality that their API is useful for and the problems that clients can solve using the API. Just by reading the API documentation, there should be enough details available for a novice to understand and use the API.

Integration Guidelines

If the API requires sophisticated integration or complex orchestrations involving multiple calls, it might be very useful to provide integration sequence diagrams and enough details that help the client achieve integration.

Authentication and Authorization  

For the Developers and Testers of your API, it might be obvious about how to use the appropriate ways to authenticate and use your API. For a newbie this is important information to have. Similarly, most of the APIs that are built now have gone from a simple single user API to APIs with complex RBAC. Details of which calls are allowed for which roles and how to obtain those roles is always helpful.

Standards Section 

As mentioned in one of my earlier posts REST is a style and not a standard. Unless you force yourself towards building or adapting some sort of standard right from the start, the APIs, even built within an organization, would end up diverging as they are built by different teams which would end up picking what they perceive to be the right way of building APIs.

The cost of bringing changes late in the game would increase multifold, frustrating both developers and people in charge of delivery. Trying to force changes late in the game without a cost/benefit analysis is a sure way to demotivate teams.

Agreeing and documenting what is perceived as standards within a specific API is the best bet in case we are close to delivery.

There are specific formats which are a bit vague when it comes to certain definitions. For example, when you are using JSON as a data format, the format is a bit weak when it comes to handling dates or money.

Choosing and documenting details of how you would like to handle things that are not covered out of the box in the format you have selected and the reasoning around why you have selected a specific approach would be helpful.

Also providing details like how common things like pagination are supported in a consistent fashion across the API would be helpful.

Just a word of caution. Anytime a new API is delivered, its “RESTfulness” is cheered as if it is the must-have feature.  Most of the successful APIs are not RESTful. Willing to make meaningful compromises, being practical about standards, weighing the benefits and the costs associated with implementing them, also matters. That said, I am not against building or adopting standards and I am just advocating  being pragmatic about their implementation costs and acting according to the implementation stage we are in.

Validation Guide & Schemas

Many people believe that publishing some sort of schema that would list all of the validations is fairly sufficient. Time and again I have seen consumers refusing to refer the schema or schema not covering enough details like second level validations. Having a schema is good. However, having an extensive validation guide that informs various validations in addition to schema, is useful.

Working Samples

I cannot reiterate the importance of working samples. In many cases, the consumers are just going to copy and try the sample that is posted on the API Documentation. Having the right sample that actually works helps the developers.

There is nothing more frustrating than incorrect samples and it is important to educate the QA Teams to treat the API documentation as a first class delivery and test it rigorously.

Multiple Samples

For an API there can be multiple API invocations. Providing multiple samples for different use cases are also very helpful.

Errors and Exceptions

While many APIs provide a good amount of details on the correct samples, they refuse to provide a fair amount of details on how different error and error responses are presented. Any consumer of the API would care about valid responses as well as responses provided by the API in case of error scenarios.

API documentation should provide enough details about the error responses and should not keep the consumers guessing what needs to be correct. 

SLA’s and Status Pages

Providing SLA’s around different APIs that are available and providing useful dashboards that inform the health of applications as well as informing any future planned outages would also be extremely useful.

Support Information

In case there are any issues or questions about the API for the consumers, there needs to be contact details available.

Live API Experience

There are tools that are capable of providing live API experience. The users are more likely to prefer documents that are capable of supporting the same.

Environment Details

Especially when you are working with Internal APIs and teams, clients would be interested in knowing details of different environments like staging, production available.

Client Stubs

More and more clients are asking for stubs in different client specific languages. They are impatient to write the code on their own and would very well appreciate client specific code in the specific languages that they use. If your API is going to cater wide variety of clients for various programing needs then it might make sense to write client-specific stubs and hand them over to the clients. This would also free some of the client cycles when it comes to coding.

Conclusion

Of the things mentioned above, a good amount of them should be supported by a proper documentation tool.

My next post will attempt to look into different tools that are available for documenting the REST APIs and the challenges we face with respect to producing API documentation.

Feel free to provide me any further details that you think should be included in the API documentation, in case there are any that I have missed.