API Endpoint Testing with Postman
Testing, reproducible results, and well defined functional specifications are the life-blood of a well designed and well functioning API. Testing itself has several phases, beginning with creating unit tests to verify operation of individual code components, through to integration testing where you start plugging pieces of your API ecosystem together.
Once your API has passed it’s unit and integration testing, the next phase is “System testing”.
System testing is defined as:
“testing conducted on a complete, integrated system to evaluate the system’s compliance with its specified requirements. System testing falls within the scope of black-box testing, and as such, should require no knowledge of the inner design of the code or logic” (https://en.wikipedia.org/wiki/System_testing).
Ordinarily in larger environments a QA team will do the System testing and will often have automated tools — however even if you are lucky enough to have a dedicated QA team on board you should be testing your own work long before it gets to them.
This is where external tools like Postman (https://www.getpostman.com) come into focus. These tools allow you to test individual routes with a variety of input options and inspect the results as you are developing.
Getting set up
For the purposes of this exercise I’m going to use the “API Testing Target” application (https://github.com/PerfectExamples/API-Testing-Target). This is an API that has simple routes for each of the main tasks common to a JSON API, and allow us to get familiar with the process.
The Readme.md of the repo also has a link to a Postman API test group.
If you want to follow along, clone the repo, build and run with the following commands:
$ git clone https://github.com/PerfectExamples/API-Testing-Target.git
$ cd API-Testing-Target
$ swift build
$ .build/debug/APITestingTargetTesting in Postman
Opening Postman, you’ll see a window similar to this:
If you’ve loaded the “Collection” then you will also see a list of requests that can be executed.
Click on the GET localhost:8181/api/v1/test/ route to load it in a tab, and “Send” to execute the request. You’ll see the resulting JSON below in the response area, as well as the HTTP Status, time and size. There are also options to inspect the “Body” (the default), as well as the “Cookies”, “Headers” and “Tests”. We won’t cover creating these tests as thats a more advanced aspect of Postman usage and is an article all in itself.
So the result of this route was a list of “users” which is really just an array of ID’s with first names. Note that the ID’s are actually randomly generated, so for the next route we will need to copy the ID of one of the users. Once we have that, click on the other GET localhost:8181/api/v1/test/646eD… route. Execute that — you should see an “error, not found” as your response.
If you replace the ID in the URL with the one you copied before, then execute again, you will see the correct response:
Creating and modifying content
The next logical step is to test creating content. Normally you would use a POST HTTP verb for creating, and the PATCH verb to update.
So lets open up the POST localhost:8181/ai/v1/test route. In the “Body” sub-tab, with “raw” selected, there should be some JSON that describes the new name to be added: {“name”:”David”}
In the response, the new ID is echoed back. We can then hit the detail GET route with that new ID and verify it’s there, or look at the list and verify it’s included.
Similarly, if we wanted to update, we would issue a PATCH request in the same way, however this time the difference is that we are including the ID in the URL.
Now, looking at the list view, the value with that ID is not “David”, but “Simon”
Now, delete.
The last part of our “CRUD” suite is to test deleting a row.
This follows exactly the same pattern as the update and detail routes: A DELETE verb with an ID.
And once again, verify with the list view:
Inspecting and using header information
The last on our test-suite list is the ability to test with or without Authentication/Session tokens. Usually these take the form of a “Bearer Token”, which is a header value of the Authorization header. The value comprises of the word “Bearer”, a space, and the authentication token which is supplied as a result of an authentication action.
We can use the GET localhost:8181/api/v1/testbearer route to test this:
To see what happens when there is none supplied, uncheck the checkbox next to the Authorization header:
There are many other things that can be done in testing using Postman — it’s a wonderfully powerful tool and can help API developers ensure consistency, quality and efficiency!
If you have any feedback, questions or even some great tips on using Postman with JSON API’s, feel free to hop on our Slack channel via http://www.perfect.ly and let me know — my handle there is also @iamjono.
