Batch requests are a way to send multiple logical requests to the MediaSilo API in a single request. This is useful when you need to deal with multiple resources that are not dependent upon one another.
An Example to Help Clarify How Batch Requests Can Help
Let's say that you'd like to retrieve a QuickLink asset, as well any comments made in reference to the asset. One way to do this would be to issue two requests to the MediaSilo API: one retrieving the asset, and the other retrieving its comments. Alternatively, you could use the Batch API. The Batch API would allow you to send both requests in a single HTTP request. By doing this, you'd be able to increase concurrent loading in your browser by offloading some to us. Also, because we can turn around the individual requests faster than you could externally, you get an overall shorter duration for the request.
Each batch request is made up of one or more logical requests. A logical request defines the HTTP method, the resource path, and optionally, a payload.
| name | description |
|---|---|
| method | The HTTP method: GET, POST, PUT, DELETE |
| payload | An optional payload to be sent with the logical HTTP request. NOTE: The payload is a JSON object. It is NOT an escaped JSON string. |
| resourcePath | The relative API path of the resource. This excludes the API version. If you have a resource at http://api.mediasilo.com/v3/me then the rousource path would be "me" |
Making Batch Requests
The following example gets an asset, gets the comments for that asset, and makes a comment on an asset.
Requests Are Run in Parallel
The requests in a batch request cannot have dependencies, because each request is run in parallel on our servers. If you have a request that is dependent on the completion of a prior request, you will not be able to send a batch request.
// Example Request Body
POST /v3/batch/
[
{
"method": "GET",
"resourcePath": "assets/1882b38c84624cac139832cb3"
},
{
"method": "GET",
"resourcePath": "quicklinks/54b3f7b05c0612b/assets/1882b38c84624cac139832cb3/comments"
},
{
"method": "POST",
"resourcePath": "quicklinks/54b3f7b05c0612b/assets/1882b38c84624cac139832cb3/comments",
"payload": {
"body": "I am a robot..."
}
}
]
Batch Payloads Are JSON Objects
Take note not to send the optional payload as an escaped JSON string. The payload is a JSON object. When in doubt, lint your JSON. If it is invalid, you can expect the MediaSilo API to return a 400 response.
Getting Batch Responses
Just as batch requests are logical requests, so are the responses. The batch response body includes a response object for each request that was submitted in the order it was submitted. The response will include the headers, too.
| Name | Description |
|---|---|
| resourcePath | The original resource path from the batch request |
| httpStatus | The HTTP status code returned from the request |
| headers | A map of the HTTP headers returned with the request |
| responseObject | The response body of the request |
The following is the response that would have returned for the above request example:
[
{
"resourcePath": "assets/1882b38c84624cac139832cb3",
"httpStatus": "200",
"headers": [
{
"Client-IP-Address": "50.169.222.45"
},
{
"Access-Control-Allow-Origin": "*"
},
{
"Content-Length": "2628"
},
{
"X-RateLimit-Remaining": "9983"
},
{
"X-RateLimit-Limit": "10000"
},
{
"X-RateLimit-Reset": "1421097587"
},
{
"Connection": "keep-alive"
},
{
"Content-Type": "application/json"
},
{
"Server": "Jetty(9.1.z-SNAPSHOT)"
}
],
"responseObject": {
"id": "1882b38c84624cac139832cb3",
"title": "io9.mov",
"description": "",
"fileName": "io9.mov",
"projectId": "2D142197-91DB-58EF-8041F5FD5B3E89F0",
"folderId": null,
"uploadedBy": "simon",
"approvalStatus": "none",
"archiveStatus": "n/a",
"transcriptStatus": "N/A",
"type": "video",
"dateCreated": 1420826546000,
"dateModified": 1420826556000,
"progress": 100,
"commentCount": 1,
"myRating": null,
"averageRating": null,
"permissions": [
"asset.create",
"asset.delete",
"asset.source",
"asset.read",
"asset.update",
"collaboration.requestapproval",
"collaboration.rate",
"collaboration.comment",
"reporting.export",
"service.transcript",
"sharing.internal",
"sharing.external"
],
"duration": 31330,
"posterFrame": "thumbnails.mediasilo.com/XX763582XXXX/1882b38c84624cac139832cb3_large.jpg",
"derivatives": [
{
"type": "source",
"url": "/XX7635823XXXX/1882b38c84624cac139832cb3.mov",
"fileSize": 3232,
"height": 480,
"width": 640,
"duration": 31330
},
{
"type": "proxy",
"url": "/XX7635823XXXX/1882b38c84624cac139832cb3.mp4",
"fileSize": 3232,
"height": 480,
"width": 640,
"duration": 31330,
"thumbnail": "thumbnails.mediasilo.com/XX7635823XXXX/1882b38c84624cac139832cb3_small.jpg",
"posterFrame": "thumbnails.mediasilo.com/337635823HFOP/1882b38c84624cac139832cb3_large.jpg",
"strategies": [
{
"type": "rtmp",
"url": "XX7635823XXXX/1882b38c84624cac139832cb3.mov",
"streamer": "rtmp://XXX758yXXXXXwg.cloudfront.net/cfx/st"
},
{
"type": "rtmpt",
"url": "337635823HFOP/1882b38c84624cac139832cb3.mov",
"streamer": "rtmpt://XXX758yXXXXXwg.cloudfront.net/cfx/st"
}
]
},
{
"type": "sprites",
"progress": 100,
"properties": {
"width": 89,
"height": 67,
"duration": 1,
"webVTT": "/assets/1882b38c84624cac139832cb3/webvtt"
}
},
{
"type": "waveform",
"progress": 100,
"properties": {
"url": "XX7635823XXXX/1882b38c84624cac139832cb3_waveform.png"
}
}
],
"tags": [],
"external": false,
"private": false
}
},
{
"resourcePath": "quicklinks/54b3f7b05c0612b/assets/1882b38c84624cac139832cb3/comments",
"httpStatus": "200",
"headers": [
{
"Link": ""
},
{
"total-results": "0"
},
{
"Client-IP-Address": "50.169.222.45"
},
{
"Access-Control-Allow-Origin": "*"
},
{
"Content-Length": "406"
},
{
"X-RateLimit-Remaining": "9984"
},
{
"X-RateLimit-Limit": "10000"
},
{
"X-RateLimit-Reset": "1421097587"
},
{
"Connection": "keep-alive"
},
{
"Content-Type": "application/json"
},
{
"Server": "Jetty(9.1.z-SNAPSHOT)"
}
],
"responseObject": [
{
"id": "54b40f153004843414091435",
"at": "1882b38c84624cac139832cb3",
"inResponseTo": "1882b38c84624cac139832cb3",
"context": "54b3f7b05c0612b",
"startTimeCode": null,
"endTimeCode": null,
"dateCreated": 1421086485,
"body": "Hi!",
"user": {
"id": "6EF6C1E9-E130-2427-8641E1A2E3DA4C8D",
"userName": "simon",
"firstName": "Simon",
"lastName": "Smith",
"email": "[email protected]"
},
"responses": []
}
]
},
{
"resourcePath": "quicklinks/54b3f7b05c0612b/assets/1882b38c84624cac139832cb3/comments",
"httpStatus": "200",
"headers": [
{
"Client-IP-Address": "50.169.222.45"
},
{
"Access-Control-Allow-Origin": "*"
},
{
"Content-Length": "35"
},
{
"X-RateLimit-Remaining": "9983"
},
{
"X-RateLimit-Limit": "10000"
},
{
"X-RateLimit-Reset": "1421097587"
},
{
"Connection": "keep-alive"
},
{
"Content-Type": "application/json"
},
{
"Server": "Jetty(9.1.z-SNAPSHOT)"
}
],
"responseObject": [
{
"id": "54b40f153004843414091435"
}
]
}
]
Be Sure to Inspect Your Responses
Just as you might receive a 400 for malformed JSON, you can also receive the same for individual requests in a batch. One well-formed request can succeed while another malformed request can fail in the same batch.
Permissions
The Batch API inherits its permissions from the underlying resources. If you have permission to make the requests directly, you can also use the Batch API for the same request.