Solution for Chapter 7: Prototyping APIs

Design and Build Great Web APIs — by Mike Amundsen (118 / 127)

👈 6: g APIs | TOC | 8: APIs 👉

In Chapter 7, ​Prototyping APIs​, we focused on translating our API design into a more-detailed working prototype using the OpenAPI Specification (OAS). The exercise at the end of that chapter (​Chapter Exercise​) contained instructions to first create a new WSD document that reflects a translation of the CreditCheck WSD diagram and the CreditCheck ALPS description document into an HTTP-style API. Then you were to take that WSD and produce a completed API definition document using SwaggerHub and the OAS format. Finally, you were to combine the ReDocly HTML template and your completed CreditCheck API definition (in JSON format) to produce a single-page interactive API document for your API.

HTTP-Style WSD File

The first step is to come up with the HTTP-style diagram of your initial API design. As you learned in Chapter 7, this act of converting the design documents (WSD and ALPS) into an implementation document (OAS) is an art, not a science. There are lots of possible solutions. The diagram is the one I created. You can use it as a guide and compare it with the one you came up with:

I saved both versions of this file (the PNG image and the .wsd text file) to the assets folder in my onboarding repository and committed them to the project using git.

Credit-Check OAS Definition

The next step was to produce a completed API definition document using SwaggerHub and the OpenAPI Specification (OAS) format. Recall that OAS documents have three important root elements: info, components, and paths. I won’t include all the documents in these pages (you can find them in the exercise/completed folder of the code associated with this chapter), but I’ll share an abbreviated version of the paths section of my OAS file. This should give you a good idea of how I used the HTTP-style WSD to guide me as I put together the API definition:

​ ### paths section ###
​ paths:
​ 
​   ### home ###
​   /:
​     get:
​       operationId: home
​       summary: Home resource for the API
​       ...
​   ### credit check list ###
​   /list:
​     get:
​       operationId: creditCheckList
​       summary: Use this to get a list of credit checks
​       ...
​   ### credit check item ###
​   /list/{ratingId}:
​     get:
​       operationId: creditCheckItem
​       summary: Use this to get a single credit check record
​       ...
​   ### credit check form ###
​   /form:
​     get:
​       operationId: creditCheckForm
​       summary: Use this to start a new credit check record
​     post:
​       operationId: creditCheckWrite
​       summary: Use this to complete a new credit check record

Notice that only one WRITE operation is exposed in this interface — the POST method on the /form resource. This implementation is perfectly valid, but it’s not very common. Often developers will POST to the /list resource. That’s fine too. I used the /form resource since most of the use of this API will be to generate a single credit-check rating, not to manipulate lists of ratings. This design will allow programmers to focus on just one URL (/form) for both READING the empty document to fill in (an option) and actually making the WRITE request to get a rating back. The other URLs are just for background use.

After completing my OAS document, I used the SwaggerHub Export function to download the “Unresolved YAML” file and the ZIP package that contained the JSON and YAML versions of my “resolved” OAS document. I added these to the assets folder in my repository and committed them to the project using git.

Creating API Documentation

The final step in this exercise was to use the ReDocly template we discussed in the chapter to create your own interactive API documentation for the CreditCheck API. For this, I just copied the HTML template from the ReDocly online repository (https://github.com/Redocly/redoc#deployment) and saved it to a new folder in my repository named documentation. I then updated one line of the template by replacing the sample OAS URL to one pointing to the URL I stored in my GitHub repository earlier.

I changed this line:

​ <redoc spec-url='http://petstore.swagger.io/v2/swagger.json'></redoc>

To this:

​ <redoc
​   spec-url="https://raw.githubusercontent.com/api-tool-kit/open-api-spec/...
​   master/credit-check-api.json">
​ </redoc>

Note that the “…” in the URL above is just for text-wrapping to make sure it fits on the book page.

Once I saved the updated template to my documentation folder, I also committed those changes to my Git repo.

With those three steps, you’ve created a WSD that reflects your HTTP-style API decisions, an OAS file that documents all the details of your working prototype, and finally a simple interactive API documentation page to include in your project.

👈 6: g APIs | TOC | 8: APIs 👉

Design and Build Great Web APIs by Mike Amundsen can be purchased in other book formats directly from the Pragmatic Programmers. If you notice a code error or formatting mistake, please let us know here so that we can fix it.