Chapter Exercise

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

👈 What’s Next? | TOC | Chapter 5 Describing APIs 👉

In this chapter, we created the WSD documents for our API workflow. That meant resolving the names and creating a WSD file that can be rendered into a completed PNG diagram.

For this exercise, we’ll do the same work using a sample credit-check service. This is a service that our customer (BigCo, Inc.) wants to eventually build and may, at some future point, include in our Onboarding API project. It’s a simple service that supports a checkCredit method while passing the companyName and return a rating value between 1 and 10. The story document (credit-check-story.md) and other supporting documents are in the code folder for this chapter. The following is the credit-check-workflow.txt document as a reference (from the code/ch04-designing/exercise/before/onboarding/assets folder):

​ ## Credit-Check Workflow
​ 
​ Home -> CreditCheckHistory
​ CreditCheckHistory -> CreditCheckForm(companyName) -> CreditCheckItem
​ CreditCheckItem -> CreditCheckHistory
​ CreditCheckHistory -> Home

Using the credit-check-workflow.txt as a guide (along with the credit-check-story.md and credit-check-form.pdf documents from the same folder), do the following:

• Create a detailed workflow document that identifies all the properties referenced in the credit-check-story.md document.
• Resolve all the data element names in the updated credit-check-workflow.txt document against the schema.org online vocabulary. This will result in an updated workflow document that includes a section on Validated Names similar to the one shown earlier in this chapter (see ​Normalizing the Onboarding API Identifiers​).
• Use the credit-check-workflow.txt document as a guide in creating your own WSD document (credit-check-diagram.wsd). This should look similar to the one shown earlier in this chapter (See ​Creating a New Diagram​).
• Finally, use the wsdgen command-line utility to generate a sequence PNG diagram from the credit-check-diagram.wsd file. This should result in a diagram that looks similar to the ones shown earlier in this chapter.

See Appendix 2 (​Solution for Chapter 4: Designing APIs​) for the solution.

Footnotes

[32] https://hbr.org/2008/06/design-thinking

[33] https://www.christenseninstitute.org/jobs-to-be-done

[34] https://schema.org

[35] https://www.WebSequenceDiagrams.com

[36] https://pragprog.com/titles/maapis/source_code

Copyright © 2020, The Pragmatic Bookshelf.

👈 What’s Next? | TOC | Chapter 5 Describing 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.