*

Making S2S API Calls from PostMan

brainCloud support two varieties of S2S calls: with and without explicitely-allocated sessions.

  • session-less
    • simpler, but less efficient
    • a disposable sessionId is automatically generated on the server (via authentication), and disposed of after the call
    • this takes time, and costs an additional API count
  • session-based
    • faster and less expensive!
    • supports request bundling
    • to use, you must first authenticate (similar to the Client API) to retrieve a sessionId, and then use that sessionId in future calls while incrementing the packetId associated with the message

Note – the session-based S2S protocol, like the client protocol, supports the bundling of several API calls within a single HTTP request. In most circumstances it is more practical to combine the calls into a single cloud code script instead. 

 

Overall, the session-based S2S protocol is recommended for production applications, because it eliminates the redundant creation of disposable sessions. It performs better and costs you less! This tutorial will show you how to simulate both types of request via Postman.

 


Installing PostMan

To install Postman, simply:

 


Pre-requisite: Configuring S2S Servers

Incoming servers must be configured (i.e. declared) in the brainCloud dashboard before making S2S calls. This allows brainCloud to confirm that the requests are coming from a server that you own and aren’t malicious.

  1. Launch the brainCloud Portal
  2. Navigate to the Design | Cloud Code | S2S Config page. Click  the [New Server] button
  3. Give your server a name, like “EXAMPLE_SERVER”
  4. Entering ip ranges restricts access to requests coming from the specified network addresses. This is highly recommended for production apps! For now though, you can leave the ranges blank. This will make all IP ranges acceptable.
  5. Hit [Save], and note your server secret – you will use it later.

 

 


Session-less S2S Requests

Session-less requests are simple. Each request is completely independent – no sessionIds or packetIds to manage. This API is best when the calls into brainCloud will be few and far between.

To simulate a session-less server request with Postman:

  1. Launch Postman
  2. Add a new Request
  3. Set the request type to POST
  4. Set the request URL to: “https://sharedprod.braincloudservers.com/s2sdispatcher
  5. In the Body section of the request, choose raw and set the type to JSON (application/json)
  6. Copy this JSON into the body, setting the appId, serverName and serverSecret appropriately for your app
    {   
       "appId": "12142",
       "serverName": "EXAMPLE_SERVER",
       "serverSecret": "b221c2a4-8df9-4937-8f9b-a95e4f71d5b6",
       
       "service": "globalApp",
       "operation": "READ_PROPERTIES",
       "data": {}
    }
  7. Select [Send]
  8. View the Response

Unless you have added some properties, you will see an empty JSON response.

To change this, go to the Design | Custom Config | Global Properties page of the brainCloud Portal and configure a property or two – then run this request again. Voila!

 


Session-based S2S Requests

Session-based requests require you to first request a sessionId to use via the Authenticate operation. You then reference that sessionId in subsequent requests, along with an incrementing packetId.

First, we need to Authenticate to get a SessionId

  1. From Postman, Add a new Request
  2. Set the request type to POST
  3. Use the same request URL: “https://sharedprod.braincloudservers.com/s2sdispatcher
  4. In the Body tab of the request, choose raw and set the type to  JSON (application/json)
  5. Copy this JSON into the body, setting the appId, serverName and serverSecret appropriately for your app
  6. (in both places!)
    {
    
       "appId": "12142",
       "serverName": "EXAMPLE_SERVER",
       "serverSecret": "b221c2a4-8df9-4937-8f9b-a95e4f71d5b6",
    
       "service": "authenticationV2",
       "operation": "AUTHENTICATE",
    
       "data": {
           "appId": "12142",
           "serverName": "EXAMPLE_SERVER",
           "serverSecret": "b221c2a4-8df9-4937-8f9b-a95e4f71d5b6"
       }
    }
  7. View the response, and save the sessionId that is returned.
  8. Now, make a second request, using that sessionId and setting the packetId to 1
    {  
        "sessionId": "df5gelac0mhrpht31fagtgatoe",
        "packetId": 1,
    
        "messages": [
            {
                "service": "globalEntity",
                "operation": "CREATE_SYSTEM_ENTITY",
                "data":{
                    "entityType": "address",
                    "timeToLive": null,
                    "acl":{
                        "other": 1
                    },
                    "data":{
                        "street": "1309 Carling"
                    }
                }
            }
        ]
    }
  9. For each subsequent request, be sure to increment the packetId. Try this one:
    {  
        "sessionId": "df5gelac0mhrpht31fagtgatoe",
        "packetId": 2,
    
        "messages": [
            {
                "service": "globalEntity",
                "operation": "GET_LIST",
                "data":{
                    "where": {
                        "entityType": "address"
                    },
                    "orderBy": {},
                    "maxReturn": 50 
                }
            }
        ]
    }

So, you get the idea.

Important things to remember:

  • Always increment the packetId – except for identical retries. If you’re retrying the same request because of a communications failure, you should keep the packetId the same (it helps the server to prevent duplicate operations from happening). If you got a response from the server though, successful or not, you should increment the packetId for you next request.

 


Service and Operation Codes

The API calls documented in the API Ref (http://getbraincloud.com/apidocs/apiref/?raw#s2s) are mapped to discrete Services and Operations on the server.

The codes, together with operation-specific parameters (specified in the JSON data object) are used to send commands to the server.

Only the API Calls in the S2S section of the API Ref can be used for S2S calls.