Documenting Data Centric APIs

Due to the standardized nature of REST APIs, it’s relatively easy to document them using method documentation in your programming language and specialized tools.

With some effort, it’s possible to create almost self-documented REST APIs. If the standard rules are followed, calls to OPTIONS provide the possible methods, and operations return URIs for the resource id and for related resources, it is quite possible to discover the API by conversing with it.

Most teams use however documentation tools like Swagger or Postman. These allow you to create small documentation websites, with the possibility to call the API and learn the response structure straight from the documentation.