Using Batch Operations with the V3 API

Document created by aaron.malenfant on Sep 27, 2013Last modified by Ryan Rutan on Jun 9, 2014
Version 3Show Document
  • View in full screen mode

What is it?

A V3 API to execute multiple requests in sequence where parameters in one request depend on the result of a prior request without requiring a round trip from client to server.

 

What are the common use cases?

Cases were responsiveness is important, if a user is waiting for the result of multiple api calls.

Pleases where client to server latency is high.  This is the case on mobile devices.

 

How do I use it?

Short description / bullet points for how the developer would use it.

 

Configuring Max Batch Sizes

Currently, the Jive platform is shipped with a default Max Batch Size of 25.  This max value can be controlled by System Admins by setting the following system properties.

  • jive.coreapi.batch.request.maxsize - Maximum number of requests allowed in a batch (default=25)
  • jive.coreapi.batch.response.maxsize - Maximum number of responses allowed in a batch (default=25)

 

Show me an example!

 

Input example:  POST to /api/core/v3/executeBatch.  Make sure the Content-Type is application/json:

[ {
        "key": "content",
        "request": {
            "method": "GET",
            "endpoint": "/api/core/v3/contents/1006"
        }                
    }, {
        "key": "comments",
        "request": {
                "method": "GET",
                "endpoint": "${content:$.resources.comments.ref}"
        }
} ]









Description of fields:

FieldDescription
keyProvides a way to refer to prior results
methodGET|POST|PUT|DELETE
endpointurl or jsonpath referrring to prior result.  The selectors use JSONPath - XPath for JSON.  A JSON path parameter must be enclosed in ${...}.  The first part 'content' before the colon refers to the previous key.  The part after the colon is the json path.

 

Example Output:

[ {
  "id" : "content",
  "href" : "/api/core/v3/contents/1006",
  "status" : 200,
  "data" : {
    "iconCss" : "jive-icon-med jive-icon-status",
    "tags" : [],
    "resources" : {...},
    "likeCount" : 0,
    "replyCount" : 2,
    "status" : "published",
    "subject" : "Busy Day",
    "parent" : "http://lt-a4-110279.local:8080/api/core/v3/people/1",
    "contentID" : "1005",
    "type" : "update",
    "parentPlace" : {...},
    "content" : {
      "type" : "text/html",
      "editable" : false,
      "text" : "<body><!-- [DocumentBodyStart:e6440b97-f25d-47f9-b13e-84b3bd82b880] --><div class=\"jive-rendered-content\"><span>abcdefghi</span></div><!-- [DocumentBodyEnd:e6440b97-f25d-47f9-b13e-84b3bd82b880] --></body>"
    },
    "id" : "1000",
   ....
} 
}, {
  "id" : "comments",
  "href" : "http://lt-a4-110279.jiveland.com:8080/api/core/v3/contents/1006/comments",
  "status" : 200,
  "data" : {
    "itemsPerPage" : 25,
    "list" : [ {
      "iconCss" : "jive-icon-med jive-icon-status-comment",
      "resources" : {...}
      ...
      "content" : {
        "type" : "text/html",
        "editable" : false,
        "text" : "<body><!-- [DocumentBodyStart:65bbc4da-f44b-4941-b09f-9e65be569314] --><div class=\"jive-rendered-content\"><span>I agree</span></div><!-- [DocumentBodyEnd:65bbc4da-f44b-4941-b09f-9e65be569314] --></body>"
      },
      "id" : "1631",
     ....
  } ]
 } 
}]









Description of fields:

FieldDescription
idThe key provided in the request
hrefThe href provided.  If the endpoint was a string, it will be returned.  If the endpoint was a jsonpath this will be expanded the result.
statusHTTP status code of the request
datathe data from the request.

 

Endpoint also support wildcards. This means the jsonpath can be expanded into multiple urls.  This is useful in messages or comments to get additional data for every comment or reply.

Input example:

[ {
   ...
        "key": "outcomes",
        "request": {
            "method": "GET",
            "endpoint": "${comments:$.list[*].resources.outcomes.ref}"
        }               
} ]










Example Output:

[{...},
{...},
{
  "id" : "outcomes",
  "status": 207,

  "results" : [ {
     "href": "http://lt-a4-110279.jiveland.com:8080/api/core/v3/comments/1001/outcomes",
     "status" : 200,
     "data": { ... }
    },
    {
     "href": "http://lt-a4-110279.jiveland.com:8080/api/core/v3/comments/1002/outcomes",
     "status": 200,
     "data": { ... }
    }]
}









Attachments

    Outcomes