Documenting your API

One often-overlooked yet vitally important aspect of a good-quality API is proper documentation. Sometimes, testers and developers can overlook documentation as something that is outside of their area of expertise. If you have a team that writes documentation for your API, it is certainly fine to have them write it, but don’t treat documentation as a second-class citizen! Documentation is often the first exposure people have to your API, and if it does not point people in the direction they need to go, they will get confused and frustrated. No matter how well you have designed your API, users will need some documentation to help them know what it can do and how to use it.

Documenting with Postman

Postman allows you to create documentation directly in the application. In Chapter 1, API Terminology and Types, I showed you how to create a request to the GitHub API. Of course, GitHub has its own API documentation, but let’s look at how you can create documentation in Postman using that API request. If you did not create the GitHub collection, you can import the collection from the GitHub repo for this chapter:

1. Download the GitHub API Requests.postman_collection.json collection file from https://github.com/PacktPublishing/API-Testing-and-Development-with-Postman-Second-Edition/tree/master/Chapter02.
2. In Postman, click on the Import button at the top of the navigation tree:

Figure 2.1: The Import button

3. On the resulting dialog, click on the Choose Files button, browse to where you downloaded the collection file, and select it.
4. Click on the Import button and Postman will import the collection for you.

Once you have the collection set up, you can create some documentation with the following steps:

1. The first thing to do is navigate to the GitHub API Requests collection and click on it.
2. Click on the View complete documentation link.

This brings up the Documentation panel.

In the top section, you can enter documentation for the collection itself, if you want. There might be times when you want to do this but, in this case, you only have one request so there probably isn’t too much documentation to put in here. Instead, you can scroll down to the next section to enter documentation for the Get User Repos request.

Note that you can also jump to a request by clicking on it in the right-hand panel, as shown in the following figure:

Figure 2.2: Going to the request documentation

In this case, we currently only have one request in this collection, so it is just as easy to scroll. However, if you have many requests, the jump navigation will let you quickly navigate to the one you are interested in. In order to edit the documentation, simply click on the area below the URL for the request and you can start typing your documentation for this request directly into the provided textbox.

NOTE:

Postman API descriptions support Markdown. If you are not familiar with Markdown, it is a simple set of rules that can be used to format text. A great resource showing the kinds of commands available is the Markdown cheat sheet, which you can find at https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet.

Let’s write down some documentation for this endpoint:

1. At this point, just type something simple in here so that you can try it out. Type in something like this: This endpoint will get information about what repos the given user has.
2. When you click away from the editing panel, Postman will auto-save your changes. However, this documentation is currently only available in this collection. You can make it more public by publishing it.
3. In order to publish, click on the Publish icon near the top of the page, as shown in the following figure:

Figure 2.3: Publish documentation

4. This opens a web page where you can choose various styling options for your documentation. Once you have set up the options that you want on this page, you can scroll down and click on the Publish Collection button to make this documentation available to others.
5. The published page tells you the URL from which you can see the documentation that you made. Click on that and you will see a nice documentation page that you can share with anyone.

When looking at this documentation, it seems a bit sparse. It could be improved with an example request showing what a response looks like. You can easily add examples in Postman with the following steps:

1. Return to Postman and go to the Get User Repos request.
2. Replace the {{username}} variable in the request URL with a valid username (you could use your own or just put in mine, which is djwester). In future chapters, I will show you how to work with variables, but for now, just manually replace it.
3. Click on the Send button for the request to send it off. If you get back an empty array, it could be that your GitHub has privacy settings that don’t allow these results to be returned. In that case, use my username (djwester) instead.
4. Now go down to the response and click on the Save as example button.

Figure 2.4: Adding examples

5. Postman will automatically add an example to this request. Return to your API documentation page and refresh it. You will now see an example request and response:

Figure 2.5: Example API request and response in documentation

It is worth spending more time exploring how to document your API well, but these features make it straightforward to do in Postman. Whether you are a tester or developer and whether you are working on a new API or one that has been around for some time, I would encourage you to take the time to properly document your API. Good documentation will make a world of difference to your users and will also lead to you and your team having a better understanding of how it works. It is well worth the time that it takes, especially when working with a tool like Postman that makes it so easy to do. In fact, although this is not a book on API documentation, it is worth spending a few minutes on some of the theory of how to write good API documentation.

Good practices for API documentation

One key practice to keep in mind when writing API documentation is consistency. In this chapter and the previous one, I have been giving you a lot of API-related terminology. There is always going to be some variation in how terms are used but, as much as possible, try to use terms in a way that is consistent with how other APIs use them. You should also try to have as much internal consistency as possible in your documentation. This means things like using the same terms to mean the same thing throughout the documentation. It also means that, as much as possible, you want your API structure to be consistent so that you don’t have to explain similar things in different ways throughout your documentation.

Writing API documentation can benefit you and not just those reading it. Sometimes, in reading or creating documentation, things will jump out at you. You might see how two things that are quite similar are laid out in very different ways. This can help you see where you might need to fix or change things in the API itself, which is another benefit of good API documentation.

Another very important thing to keep in mind when it comes to API documentation is the importance of examples. We already saw how easy it is to make examples in Postman documentation. Take advantage of that! It has been said that a picture is worth a thousand words. I think that an example in an API doc is worth nearly as many. Some things are difficult to explain well in words and it takes seeing it done in an example for people to grasp how it works. Do not underestimate the power of a well-crafted example.

One final thing to keep in mind with API documentation is a problem that happens with all documentation. It gets out of date. Code changes, and that applies to API code as well. Over time, what your API does and the exact ways that it does it will change. If you don’t keep your documentation up to date to match those changes, the documentation will soon cease to be useful.

You have already seen how you can keep your documentation right with your tests and how you can generate examples directly from your requests in Postman. Take advantage of that and make sure your documentation stays up to date. Postman will take care of a lot of the work for you by updating all the documentation automatically every time you publish.

There are some specification tools that can help automatically generate documentation. These kinds of tools can help keep documentation and tests up to date with the latest code changes. I will take you through some of those in more detail in Chapter 4, Considerations for Good API Test Automation. In that chapter, I will particularly focus on the Open API specification, as it is a powerful and popular API specification tool, but there are other API specification tools that we can use.

There is an ongoing debate in the API development community that mirrors broader debates in the software development community as a whole. The debate boils down to how much time you should spend upfront on design. Some will argue that since the only good software is software that helps someone solve a problem, we need a “ship first” mentality that gets our ideas out there. We then fill out the design based on the kinds of things clients actually need and care about. Others will argue for a “design first” approach, where you rigorously define the API behavior before you write any code. As with most things, you are probably best off avoiding either ditch and finding the middle ground between them.

Modern tooling can help us do this. For example, there are tools that will allow you to create simple designs and then use those designs to get feedback from clients. One tool that is helpful for API design is specification languages. These are sets of rules that can be used to define the way an API is expected to work. As we look into how to design APIs, let’s look at a specification language that is meant to help shift the focus away from merely documenting an API and toward helping with API design.

RESTful API Modeling Language

RAML, which stands for RESTful API Modeling Language, is an API specification language that, as the name implies, helps with modeling APIs. You can read more about it on the RAML website, https://raml.org/. RAML has some tools that can help with API design but getting into those is beyond the scope of what I want to cover in this book. For now, I just want to introduce you to this specification and let you see how you can use it to design an API that meets the design criterion I’ve talked about in this chapter.

Getting started with RAML is as easy as opening a text editor and typing in some text. RAML is meant to be human-readable and so the specification is written in a simple text-based format. RAML is also structured hierarchically, which makes it easy to create the kind of usable API structures that I’ve talked about. In the next section, I will walk you through an example of using this modeling language to design an API and leverage the power of that design in Postman. You will then get to try it out on your own as well!