Try out the Stream API with Postman

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.

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.