At Aquil.io, developing APIs and collaborating with clients walk hand in hand. Communication is essential in any consulting environment, and explaining information about a Feathers service is most effectively done with executable code, close to the metal. To control a test and increase the reliability of the result, it is important to remove as many moving parts as possible. We leverage this philosophy in all parts of our workflow. Postman is a tool that allows us to create predictable and consistent requests against APIs. It is a tool we regularly use in debugging APIs.
To aid in collaboration with client development teams, we create a repository of requests in Postman, allowing us to then export and share requests in various formats, such as curl. For this article’s purposes, we assume a Feathers API is being developed. When looking to test or debug with Postman, be sure to configure the Feathers REST transport. Postman does not currently work with WebSockets. However, RESTful and WebSocket requests execute the same hooks and service methods due to the Feathers transport abstractions.
Create the workspace
Though requests can be created in the default workspace, in practice, this can become an unmaintainable list quickly. We create a workspace to group requests by project. Personal workspaces can always be converted to team workspaces later. There is an in-depth article on workspaces on the official Postman blog.
Leveraging variables and environments
APIs we develop fall into a few environments, depending on the project. Commonly, this is categorized as local, staging, and production. We run requests against different environments using the environment switcher. Within our requests, we use variables defined at the environment level and updated based on the environment we select. In most scenarios we use two variables, host and token.
The request, in most cases, will require authentication. There are several options that authenticate a request with the service. The chosen authorization will modify the request with the appropriate headers or preflight calls. We use the Bearer Token option and apply the token for the request.
We create a new environment in Postman named after the environment itself. We add a host variable and an authentication token variable, naming it token.
We create environment representations and define the appropriate variables.
Create collections and requests
To us, collections are synonymous with Feathers resources. Treating a collection as a representation of a resource allows for an intuitive grouping of requests.
We create a collection named after the Feathers resource. We select Bearer Token on the Authorization tab and apply the token variable to the Token field.
We create a request within the appropriate collection, using the environment variables to build the final request. Each request we create uses the host token from the chosen environment and, for authentication, we select Inherit auth from parent. This will carry over settings for authorization from the parent collection.
A request setup in this way allows us to run a request on any environment by changing the environment and sending the request.
Naming the request is valuable for communicating intent. We consider the verb in our naming convention so it reads like plain English. Feathers closely ties service objects to HTTP verbs. This connection makes the title valuable in identifying and finding a request within a list of requests.
Feathers conventions such as:
becomes:
Sharing requests
When our team needs to collaborate on an endpoint, such as for debugging, Postman can easily export a curl request. A curl request is a simple and easily shared representation of the request. We prefer curl requests over alternatives such as sharing UI walkthroughs. Browser configuration, like caching or plugins, might interfere with the request. A UI application will accept a request’s response and derive an interface based on the data. The interface is not a one-to-one relation to the data. Collaborating around a curl request removes variability.
Conclusion
It is important to note that using Postman does not replace the need for tests. We borrow much of our testing philosophy from the testing pyramid and use Postman in tandem to accelerate our development process. Requests in Postman will execute hooks, middleware, service objects, and data stores. Postman effectively acts as an ad hoc integration test.
At Aquil.io, we implement a deterministic strategy for processes. We look for efficient and straightforward solutions. When we integrate a tool into our workflow, we expect the tool to complement our strategy and improve productivity. Additionally, communication is a vital part of our strategy. Postman enables short feedback loops and communicates dense information succinctly making it an essential tool to our development process.
Originally published at https://aquil.io on September 16, 2020.
If you want to check out what I’m working on or have web development needs, visit Aquil.io.
How we debug Feathers APIs using Postman was originally published in DailyJS on Medium, where people are continuing the conversation by highlighting and responding to this story.
