Postman is a great 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.
At Stream we use Postman regularly when 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.
Our APIs requires a JSON Web Token (JWT) for each request. With Postman it is possible to create these JWT tokens dynamically. This drastically increases the ease of use when exploring our APIs.
What's in the Collection
The collection is loaded from our OpenAPI specification and demonstrates all of Stream's major features as well as the individual API call.
You can find our Postman workspace here.
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 which Stream makes use of. Thanks to another helpful Postman feature called Pre-request Scripts we have an elegant solution. For requests to Stream's API, a bit of JavaScript program first generates a JWT and populates the HTTP request header on each request.
// JWT generation script adapted from
// https://gist.github.com/corbanb/db03150abbe899285d6a86cc480f674d
var jwtSecret = pm.environment.get("jwt_secret") || "";
var apiKey = pm.environment.get("api_key") || "";
// Set headers for JWT
var header = {
typ: "JWT",
alg: "HS256",
};
// Prepare timestamp in seconds
var currentTimestamp = Math.floor(Date.now() / 1000);
Often a 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 "production" environment. This environment requires setting your api key and api secret.
Wrap up
If you are interested in the running the Postman Collection, head over to the Stream's workspace on Postman. Enter your credentials in the "Production" environment and you should be able to start sending requests to your backend.
