Postman - how helpful can a mailman be in creating an API.

One that has dozens of different endpoints (if not too large). Where every GET request can contain many different combinations of parameters that interest us. Where every POST can send complicated JSON structures. Where practically every request can, but doesn't have to, have certain HTTP headers on which the behavior of our application depends (e.g. Authorization, Content-Type, etc.). And on top of that, we still have to create and maintain documentation for our API.

Suddenly, the browser and cURL don't look so great anymore. Fortunately, the people at Postdot Technologies have decided to simplify this for us, and it's completely free!

Surely anyone who has had their hands in creating an API has come across an application called "Postman" at some point. It can be installed as a system application or as a browser extension."

In the above screenshot, we can see that we can easily create a collection of requests that interest us. Each of them can have saved sets of data, parameters, headers, cookies, etc. Additionally, we can conveniently browse the response - we can copy the entire response to the clipboard with one click, search the content, and collapse long nodes in JSON. It may seem like nothing special, but it's impossible to overestimate the time it saves us in total when working on a multi-month project.

Moreover, we can easily share our collection of requests with anyone we want. The "Share" window shown in the screenshot below is available for each of our collections, where we have a unique link available. This link contains a JSON file, which is nothing more than our entire collection of requests. When another user with the "Postman" extension clicks on the link, the entire collection will be automatically loaded or updated. We can update the data in real-time by clicking the "Update link" button. It's really handy and worth including in the README, for example.

But that's not all. When we painstakingly prepare our rich collection of requests over time, giving each of them a meaningful name and enriching them with a description, we can generate a very decent HTML documentation with just one click. And it's even responsive. How do we do that?

Simply select the "View in web" option from the collection menu, which allows us to preview it. Once we're satisfied with it, all we need to do is select the "Publish docs" option, which allows us to share the documentation under a unique link. And importantly - it will update along with our collection in the application - we just need to save changes to any of our requests.

For each endpoint, we see the full URL, a list of headers, and in the case of POST requests, we also see the sent data. On the right side of each method, we have a ready-to-copy cURL version, but we can also easily change it to ready-made requests in jQuery, Ruby, Go, PHP, and other languages.

If you're working on developing an API in your application, you should definitely check out Postman. It allows you to focus on the logic of your application instead of tools, and automate the creation of basic documentation. It also becomes a reliable source of current information, mainly because sharing the collection with other team members is incredibly easy, and documentation updates itself during work.

Additionally, in the current version, it is possible to mock servers and test APIs, which makes Postman a complementary tool for working on these types of projects.