Solution for Chapter 4: Designing APIs

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

👈 3: APIs | TOC | 5: ing APIs 👉

In the ​Chapter Exercise​, you were instructed to complete a detailed version of the credit-check-workflow.txt document, resolve the names in that workflow against the https://schema.org site, and then use that updated workflow document to create your credit-check-diagram.wsd document. Finally, you were instructed to use that WSD document to generate a PNG diagram of the CreditCheck service workflow.

Detailed credit-check-workflow.txt

This first step involves making sure you include possible property values and navigation actions that will be exposed by the CreditCheck service. This is also a good time to resolve any property names against your company dictionary to make sure you only expose names that everyone else using your API already understands. I combined both steps into one and produced the following updated credit-check-workflow.txt document:

​ ## Credit Check Workflow
​ 
​ Home -> CreditCheckHistory
​   [ratingId, companyName, dateRequested, ratingValue]
​ CreditCheckHistory -> CreditCheckForm(companyName) -> CreditCheckItem
​   [ratingId, companyName, dateRequested, ratingValue]
​ CreditCheckItem -> CreditCheckHistory
​   [ratingId, companyName, dateRequested, ratingValue]
​ CreditCheckHistory -> Home
​ 
​ Validated Names:
​  * ratingId := https://schema.org/identifier
​  * companyName := https://schema.org/legalName
​  * dateRequested := https://schema.org/Date
​  * ratingValue := https://schema.org/ratingValue

Create a WSD Document

The next step is to create a web sequence diagram (WSD) version of the workflow. I created one called credit-check-diagram.wsd that looks like this:

​ Home -> CheckCreditHistory:
​   [ratingId,companyName,ratingValue,dateRequested]
​ CheckCreditHistory --> Home:
​ CheckCreditHistory -> CheckCreditForm:
​ CheckCreditForm -> CheckCreditItem: (companyName)
​ CheckCreditItem --> CheckCreditHistory:
​   [ratingId,companyName,ratingValue,dateRequested]
​ CheckCreditHistory --> Home:

Generate a PNG File

Finally, I used the wsdgen utility to generate a PNG version of the WSD file using the following command-line action:

​ wsd-gen credit-check-diagram.png

This generates the file credit-check-diagram.png, which should look something like this:

Be sure to save your project updates using git too.

👈 3: APIs | TOC | 5: ing 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.