Save and Document WebSocket Requests in Collections

Udit Vasu

October 19, 2021

Earlier this year, we added support for WebSocket and Socket.IO, enabling debugging and testing for these new request types. Since then, we have been working towards adding the ability to document and save WebSocket requests within Postman Collections.

We are excited to announce that with our latest release, you can now save and document your WebSocket requests within a collection. This capability is built as a foundation for our upcoming improvements to support more synchronous and asynchronous protocols.

Related: Postman Collection best practices

Saving a WebSocket request in a collection

From a WebSocket request tab, click Save in the header(or, ⌘ + S) to open the request save modal. You will notice that it asks to create a new collection for saving WebSocket requests.

Click Create collection and name your new WebSocket collection. Finally, name your request and click Save.

For the moment, you will need to create a new collection and exclusively store WebSocket requests in them.

Saving WebSocket messages

A WebSocket request is incomplete without the messages that the API accepts. To save your very first message, click Save Message and give your message a meaningful name, then hit Enter.

To draft a new message, switch back to the Compose Message and author a new message.

Pro Tip: You can save messages from the messages stream as well by hovering over a message and clicking the save icon.

Documenting your WebSocket APIs

As you’re probably familiar with, a Postman Collection also acts as your API documentation, and these collections are no different. You can document your collection and requests to help your API consumers better understand the APIs.

In a request tab, you can access the documentation from the context bar on the right. You will notice your API documentation is autogenerated from the saved request and the messages:

For Socket.IO requests, you can supercharge your API documentation with the help of events. In the Events tab, add the events associated with the request and in the documentation view, the saved messages automatically get categorized by the event names.

What’s next?

The ability to save and document WebSocket APIs was, in fact, the most requested feature after our initial WebSocket release. It is still the first step for asynchronous APIs to nestle within the API lifecycle, and we’ll be incrementally adding support for more features like scripting, testing, and forking.

We would love to hear your continued feedback so that we can keep creating and evolving what helps you to build faster and better. We invite you to participate in the Postman Community forum discussion around WebSocket support and follow our GitHub issue tracker link in order to talk to us about improvements, ideas, and issues. Finally, we’re excited to see your WebSocket APIs, so share them in public workspaces.

Try Postman now