Documenting contracts

Unlike soap style messages where the Web Services Description Language (WSDL) defines a robust contract between the consumer and service provider as an XML document, there was no such metadata exchanged when consuming a REST service until WSDL 2.0 was released.

Textual documentation still seems to be popular with developers to describe the available methods and entities. There is a NuGet package available for MS Visual Studio, which automatically generates help page content for Web API projects. It can be installed using the Package Manager Console using the following command: PM> Install-Package Microsoft.AspNet.WebApi.HelpPage.

Swagger, which is an open source product is also very popular among developers for generating interactive documentation and client SDK generation and discoverability. More information can be found at http://swagger.io/. Swagger appears to be Microsoft's tool of choice for API documentation as it has been adopted in many products in the Azure suite.

Another tool is RESTful API Modeling Language (RAML), which provides a contract first approach of modeling web APIs. This uses a derivative of YAML (YAML ain't markup language) and JSON to create a human- and machine-readable document. More information can be found at http://raml.org/index.html.

To help the consumers of the service, the messages should be self-descriptive, and you should be able to understand the requests and responses after spending minimal time using the service and reading the documentation. In the end, the URL structure has a large part to play in the overall usability of the service.