As many developers are aware, Postman is a fantastic tool for developing and testing RESTful web services and APIs. Since its inception, Postman has evolved beyond simply sending HTTP requests into a feature-rich product with support for automated testing and team collaboration.

Many of us at Stream use Postman regularly as we build and test our services. We're also always looking for ways to make it quick and easy for other developers to try the service. One of our goals is to help people see first hand how simple it is to build powerful social apps with Stream.

When we realized that Postman's newest features provide an opportunity to bundle API request examples, and perform more advanced steps like generating JSON Web Tokens (JWTs) for each request, we were keen to give it a shot with Stream. We're now happy to publish a Postman collection that demonstrates all of the RESTful API endpoints to the Stream service.

The Stream API Postman Collection

Those who're itching to try it out can head to the Stream documentation and download the collection.

If you'd like to learn a little more about what's in the collection and how we built it, read on.

What's in the Collection

The collection contains around 30 requests that demonstrate all of Stream's major features as well as the individual API calls that correspond to each step in our Getting Started tutorial. This covers adding and modifying activities, retrieving feeds, and maintaining the follower relationships in order to maintain the social graph within an application. This will no doubt broaden even further as we add new API endpoints and expanded features.

One challenge we faced in building the collection was setting up an authentication mechanism to ensure Stream would accept and process the requests initiated by Postman. Although Postman supports several common authentication mechanisms like HTTP Basic Authentication, OAuth, and Bearer Tokens, it lacks built-in support for generating the JWTs that Stream makes use of. Thanks to another helpful Postman feature called Pre-request Scripts, we were presented with an elegant solution. For the Stream requests, a simple custom JavaScript program first generates a JWT and populates the HTTP request header on each request.

The Collection-level Pre-request script generates a JSON web token for authentication.

As with all but the most non-trivial APIs, each request includes dynamic data and parameters that relate to the resource and/or operation being requested. Configuration and 'secrets' for authentication purposes are also needed. To avoid unnecessary setup steps, we embed appropriate configuration for a "starter" app. This configuration can be updated later via Postman's environment variables.

Finally, we wanted to not only demonstrate the requests but also help developers begin to understand how they themselves can work with the Stream service. With Postman's focus on quality API documentation, we were able to include explanations of each resource URL fragment, HTTP header, and the request body (JSON payloads) that are sent. This includes the optional parameters and references to our online API Documentation where more guidance on advanced use cases can be found.

Descriptions are provided for URL query string parameters, body fields, and HTTP headers.

Wrapping Up

If you're interested in the running the Postman Collection, head over to the Stream documentation to download the collection. Fire up Postman and following the README instructions. Don't forget to star us and feel free to raise issues or submit pull requests if you see any areas for improvement.

This is our first attempt at packaging and sharing a Postman Collection so we're curious what you think. Chime in on Twitter or shoot us an email at with your thoughts.