Try out the Stream API with Postman

2 min read
Jeroen L.
Jeroen L.
Published December 21, 2022

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.

javascript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
// 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) var data = { 'iss': pm.environment.get('jwt_iss') || '', 'ist': pm.environment.get('jwt_ist') || '', 'iat': currentTimestamp, 'exp': currentTimestamp + 30, // expiry time is 30 seconds from time of creation 'jti': 'jwt_nonce' } function base64url(source) { // Encode in classical base64 encodedSource = CryptoJS.enc.Base64.stringify(source) // Remove padding equal characters encodedSource = encodedSource.replace(/=+$/, '') // Replace characters according to base64url specifications encodedSource = encodedSource.replace(/\+/g, '-') encodedSource = encodedSource.replace(/\//g, '_') return encodedSource } // encode header var stringifiedHeader = CryptoJS.enc.Utf8.parse(JSON.stringify(header)) var encodedHeader = base64url(stringifiedHeader) // encode data var stringifiedData = CryptoJS.enc.Utf8.parse(JSON.stringify(data)) var encodedData = base64url(stringifiedData) // build token var token = `${encodedHeader}.${encodedData}` // sign token var signature = CryptoJS.HmacSHA256(token, jwtSecret) signature = base64url(signature) var signedToken = `${token}.${signature}` console.log('Signed and encoded JWT', signedToken) pm.request.headers.add({ key: "Authorization", value: signedToken }); pm.request.headers.add({ key: "api_key", value: apiKey }); pm.request.headers.add({ key: "Stream-Auth-Type", value: "jwt" });

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.

Integrating Video With Your App?
We've built a Video and Audio solution just for you. Check out our APIs and SDKs.
Learn more ->