Documenting REST API

In the last post, I noted that I have been documenting REST APIs for the last couple of years. The documentation is manual (not automated to generate documentation out of code comments). We have a template to follow for documenting the basic components, such as headers, methods, request and response classes, and parameters and messages. We are looking into various tools to streamline the process, including Swagger (http://swagger.io).

Stephen Judd of OpenCredo gave Swagger a positive rating in his article Documenting REST APIs – a tooling review (July 28, 2015). Judd describes the tool, and his experience using it with the Java library Springfox. He provides an example Books API to illustrate the outcome. This screenshot from Judd’s article shows the GET method tab expanded, with documentation for the response class.

Swagger-UI-Screen-Shot-2015-07-17-112618

The resulting documentation is attractive and straightforward. The Swagger tool includes an Editor for designing the API specification, and a Web UI that converts the specification into API documentation in web page format. A tool like Swagger would definitely improve the documentation process.

What is REST Anyway?

I have been documenting REST (REpresentational State Transfer) for a couple of years now, especially for push notifications. Our team has been calling it the REST API, but the documentation style is distinctly different from other APIs I have documented. Headers, requests, responses, GET, PUT – it looks less like an interface layer, and more like a communications layer for exchanging bits of information across the Internet. So what is REST anyway? I decided to learn a little more.

REST is an architectural style, and a method for communications used in Web services. It is based on an architecture described by Roy Thomas Fielding in his dissertation in 2000, Architectural Styles and the Design of Network-based Software Architectures (a surprisingly accessible read). The REST approach is similar to SOAP (Simple Object Access Protocol), but lighter weight. REST typically runs over HTTP (Hypertext Transfer Protocol); is used for mobile applications, social networking Web sites, and automated business processes; and is popular for cloud computing.

This WebConcepts video introduces REST concepts and terms, and uses familiar applications, such as Facebook and Twitter, to illustrate them. The video also introduces Postman, a useful tool for testing and researching REST communications. Between Fielding’s dissertation, and a few videos, I have a good foundation for learning more about REST.