REST API Documentation
REST APIs are the Future
Handling information across HTTP is the principle of the Web. Each time you’re googling something, or using your mobile app, you’re trying to access resources from the distance across HTTP. The purpose of REST APIs is to access resources that are in the cloud, giving the paths to access them. The strength of REST APIs is that they are language agnostic. They use either JSON or XML as message format: thus, they are universal. 20 years ago I worked for a cross-platform message broker whose SDK was available in C++, Java and C. This was a way to allow language-dependent platform to communicate with each other. We’ve come a long way since!
RESTful API and OpenAPI
Being more and more popular, REST APIs tend to have standards: are they RESTful or not? Does it entirely match the design pattern? Yes, they’re RESTful. Else, they’re just REST.
I like this joke:
Credit image @Octo
OpenAPI is a specification for describing REST APIs using JSON objects. This standardization eases the work of parsing tools, and there is now a wide variety of publishing tools from the default Swagger Editor, to neat and attractive templates.
The good in OpenAPIs (for doc authoring) is that the API and the documentation are in the same file. You write the documentation by adding description lines into the OpenAPI file, and that’s it. This writing task closest to the code is fun.
Coffee Cup Services in REST API Documentation
The documentation can be written in either English, French or German
Coffee Cup provides services in REST API documentation, whatever your API uses JSON or XML. I love doing this!
Will your Documentation be “DOCful”?
|DOCful| is a play on words of my invention that alludes to RESTful 😃. However, it is not just for fun. It also aims to establish some kind of standard on REST API documentation.
A DOCful documentation should consist of a Reference documentation and a User documentation.
-
The documentation made in the OpenAPI file from the description fields is a reference documentation. Routes, methods, keys & values and returned codes are documented systematically and as exhaustively as possible.
-
The documentation should be supplemented by a user documentation. Since it is outside the OpenAPI file, we can write the content in Markdown files and use a static site generator for the publication, which makes it very attractive and professional.
User documentation includes:
- Overview, schemas, background information
- Getting started
- Tutorials
- Status & error code lists
- Glossary
Even if you can add text and images/diagrams in the introduction part of the Swagger file, this is not the place to “spread out”. The right place for such information is in the User documentation.
I recently tested Docusaurus V2, which is a very good static site generator with powerful features and really nice styling options. Its challengers, i.e. Jekyll and VuePress, are very good alternatives.
In the perspective of a DOCful documentation, I really appreciated the ReDoc plugin developed for Docusaurus V2 that allows to have a single Documentation portal to access both the user documentation and the OpenAPI.
If you rather have documentation apart from the API, this is also possible. Information will be “extracted” from the code and structured into a file.
🔗 See my Portfolio
🔗 Read more, see my Favorites
Tools
Swagger Editor, Git, Visual Studio Code and any other tools required to read/modify/push code. A static website generator to have a good rendering (e.g. a ReDoc template).
The present website uses the Markdown syntax, the static site generator Hugo and a nice template.