Document it

The service must be well-documented for it to be useful. The Web API contract of a service can be published via documents which are manually built or generated automatically using various build tools. SOAP APIs have a WebService Description Language (WSDL) used to describe the service, but REST APIs do not have an equivalent. Given the growing popularity of REST, there are other solutions that have come up to fill this gap. A possible choice for documenting REST resources is Swagger. There is the Open API Initiative (OAI) that is working to standardize REST API documentation. The specification is based on Swagger, which defines the metadata that is used for documenting APIs.

Developers can make use of the maven Swagger plugin to generate an API document for their microservice. There are other options to generate or document your APIs, but Swagger does bring compelling features that make it an appealing choice. It potentially frees up the developer from having to update the documents manually. There are some goodies it offers, such as the ability to generate API information in a readable format that contains the REST resource name, URL, HTTP method, and request and response formats. It also generates JSON or YAML files which can be used by other tools to provide easy generation of client libraries tailored to the service.

Some good qualities to have in documentation are:

• It should be easy to generate and rely on the code itself, which is the best source of truth.
• The presentation of the document should be readable for humans and available over the web for browsing.
• Should contain samples, describing the service.
• The ability to try out a service based on its documentation can be a valuable addition.
• Separation should be maintained between what is public API and what is private API. Things which are to be used by others can be termed public API, but APIs that are internal to a service should be flagged accordingly.
• Clearly state the current and previous versions of the APIs published.

When using document generation tools, the generated documentation can itself be hosted in some source repository or Docker registry (more on this later). This allows it to be versioned and referenced by the team when required.

References:

• Swagger: http://swagger.io/
• Open API Initiative (OAI): https://www.openapis.org/
• Maven plugin: https://github.com/kongchen/swagger-maven-plugin