API Documentation and Design

I believe that design, testing, and documentation are just as much a part of creating a quality product as development is. Perhaps they are even more important. You might find it surprising that a book on testing is spending so much time talking about documentation and design, but both of these practices are also key contributors to quality.

Good design can make the life of a developer or tester much easier. Designing something isn’t so much about making it look good as it is about ensuring that it brings satisfaction. We, humans, enjoy things that look nice, so designs can sometimes be focused on the look and feel of something, but even in the realm of APIs, where there isn’t much to “see,” good design can make it much more enjoyable to use and thus improve the quality.

Good documentation also makes the life of a developer and tester much easier. I have struggled through working with APIs that have missing or incorrect API documentation. It makes it much harder to work with and test the API. You can spend hours trying to figure out how to make one call simply because there is one missing parameter that you need to include for the call to work, but with good documentation, you could have figured that out in minutes.

This chapter will go over the principles of API documentation and design and cover the following main topics:

• Figuring out the purpose of an API
• Creating usable APIs
• Documenting your API (with Postman)
• API design example (a practical exercise)

The material in this chapter can feel a bit abstract and theoretical, but I have included a few exercises to help you figure out how to use these concepts in practice. I would encourage you to spend the time to work through those exercises and, by the end of this chapter, you will be able to use these design principles to come up with great insights for APIs that you are currently working on, as well as having a strong foundation that you can use if you need to create a new API. This chapter will also help you get started with API documentation in Postman and show you how to use the RAML specification language to design and model an API and to automatically add requests into Postman.