Using Batch Operations with the V3 API

Version 3

    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": { ... }
        }]
    }