Do you want to transition into documenting REST Application Programming Interfaces (APIs)?
Are you a developer who wants to learn how to document the APIs that you create?
Do you want to add to your technical communication toolbox and skill set?
Are you a current student or life-long learner who wants to learn something new?
STC Carolina hosted Tom Johnson for a live, hands-on workshop version on Saturday, April 6, 2019. We met at the McKimmon Conference and Training Center on the campus of North Carolina State University. Tom of I’d rather be writing has created content and exercises that can help you learn about REST APIs and how to document them. After Tom introduced himself and his technical writing background, he led a discussion of our goals to find out what we wanted to get out of the workshop. In preparation for the workshop we had to download and install several programs. You can find the list here.
Introduction to API Documentation
Tom briefly mentioned different types of APIs before defining and focusing on REST APIs. REST stands for Representational State Transfer. REST APIs are a type of web service because they use HTTP (HyperText Transport Protocol) and involve requests and responses like a web page. Tom shared Jim Bisso’s illustration of comparing APIs to a calculator—you input a request to perform an operation on some numbers (such as adding 1 and 2), stuff goes on behind the scenes to handle the request, and the calculator responds with the result of the request (3). REST APIs are very popular and have been growing exponentially for several years. REST API documentation is also very popular because “the documentation is the user interface”. REST APIs follow an architectural style instead of a standard message format. Therefore, documenting them is not as rigid as documenting standards-based APIs such as Java APIs, but documentation is necessary to determine how to interact with a REST API.
Using an API like a developer
If you missed the workshop, you definitely missed out on things that you don’t get in the online content such as participating in the group discussions, meeting and talking to fellow technical writers, and getting immediate answers to questions and help with the exercises
Documenting API endpoints
We learned about the five different sections that are typically covered in REST API reference documentation:
- Resource description: Actions that the resource accomplishes such as getting weather information.
- Endpoints and methods: How you access the resource and allowed operations such as GET or POST.
- Parameters: Options to control the response such as units for the wind speed. There are four types of parameters: header parameters, path parameters, query string parameters, and request body parameters.
- Request example(s): One or more sample requests to the endpoint that include meaningful parameters. In many documents the example is written in curl format but can also be written in one or more programming languages.
- Response example and schema: An example that illustrates the response from the request example and a schema that lists and describes all possible elements in a response.
The terminology is from the OpenAPI specification, but not all REST API documentation uses the same terminology. Therefore, when reviewing different API documentation, the different sections can be named using different terms.
We concluded this section with the following exercises:
- Analyzing an API reference topic and indicated all the issues and errors in it.
- Reviewing the reference documentation for an API and tried to pinpoint the five different reference sections even though the content contained different formatting and different naming of the sections.
OpenAPI and Swagger
There have been several attempts to specify standards for REST APIs. There are currently three popular ones with OpenAPI (formerly known as Swagger) emerging as the leader. Swagger terminology is still known and used. It now primarily refers to the tools to support REST APIs such as the Swagger API and the Swagger UI. Tom compared the OpenAPI specification to the DITA specification but with JSON objects (often expressed in YAML) rather than XML elements. Instead of manually creating your specification document in a text editor, you can create it in Swagger UI, which will also validate it against the OpenAPI specification as you create it. You can also generate the content from annotations in the code itself by including the appropriate Swagger CodeGen libraries and including the correct annotations and content in the code. OpenAPI and Swagger UI let you not only document your API, but let you test it and let users try it out.
The Swagger editor supports specification-first development instead of documenting completed code. API versioning is difficult, so it’s better to get the API right before coding. Specification-first development lets you perform user testing with mock responses before actually coding the API. Unfortunately, OpenAPI and Swagger only cover the reference portion of API documentation. You must take into consideration how to integrate the Swagger UI with your other documentation. Also, be careful when using the Swagger UI try-it-out feature against live data—you don’t want to order too many products from an online company when playing with an API.
We worked through an exercise in which we pasted the sunrise and sunset API specification document into the Swagger Editor so that it replaced the petstore API in the Swagger UI. In another, we used Stoplight to view the OpenWeatherMap API. The following walks you through a third exercise that we did to download the Swagger UI project from GitHub.
- Unzip it and copy out the folder needed
- Copy an API specification document to the folder, and
- Edit the index.html file to replace http://petstore.swagger.io/v2/swagger.json with the name of the API specification document.
- View the index.html file using the FireFox browser to see the OpenWeatherMap API in Swagger UI format.
Conceptual content in API Documentation
We spent most of this section on the activity to evaluate conceptual API content from different companies and discussed which company’s documentation we thought was better and why. We discussed overviews, getting started, authentication and authorization, status and error codes, rate limiting and thresholds, and code samples and tutorials.
Publishing API Documentation
We were running out of time, so Tom went through this at a very high level. I’ll definitely revisit this part on his website. The workshop was a good introduction to documenting REST APIs, but it was very fast-paced and didn’t cover all of Tom’s content. Visit Tom’s website for Testing API Docs and much more. Now I’m going through the content online to reinforce what I learned in the workshop and learn the content that we didn’t have time to cover.
If you missed the workshop, you definitely missed out on things that you don’t get in the online content such as participating in the group discussions, meeting and talking to fellow technical writers, and getting immediate answers to questions and help with the exercises. However, you can also learn at your own pace on his blog, under the API documentation menu option (or on Tom Johnson’s blog here).