Batch Request

POST /batch
Copied
Arrow
                https://api.ocamba.com/v2/ocamba/batch

Batch request is a set of requests that are executed in a non-transactional manner.

Request
Each call within the batch request is referred to as a subrequest(request part). The object that contains all of the subrequests is referred to as the main request. Once all subrequests are complete, a consolidated response is passed back to the sender. By default all subrequests are processed in parallel since they are considered as independent. This can be changed using mode parameter in the main request. Set it to serial to process all subrequests sequentially.

Response
Each subrequest has corresponding subresponse (response part) and subresponses appear in the same order as the corresponding subrequests. When the response to a batch request contains a response code of 200, it means the main request itself was well-formed. However, each individual subrequest may have succeeded or failed. Response needs to be processed on the client side to determine which subrequests were successful and which failed.

Limitations
Batch requests are limited to a 50 subrequests. Each call within the batch is counted and logged separately for the purposes of calculating API rate limits and preventing abusement. Also, be aware that main requests are subject of server limitations such as maximum size of a request body. Thus, it is possible for a batch request to be too large to process, even if the number of subrequests is at or below the allowed maximum. Limitations are also applied on subrequests, like url size, header size and request body size.

Abort on fail
Used only for serial Batch Request. If ’true’ all remaining requests will be skipped after first fail.

Errors
Its possible that one of subrequestes may throw an error. This could be because, for example, you don’t have permission to perform the subrequest or validation rules are broken. Each subresponse that results in error will contain an error message described by the standard Ocamba Error Schema.

Timeout
TODO

Request Body Schema
Arrow
Name
Description
modestring
Here goes description


Example: parallel

Possible values: parallel | serial
parts[ batch-request-part ]

Batch Request part
Name
Description
abort_on_failboolean
Used only for serial Batch Request. If 'true' the remaining requests will be skipped.
body
Subrequest payload, can be any value - string, number, boolean, array or object. In the most cases these will be a key value pairs.
headersobject
Subrequest headers used to describe subrequest message body.
methodstring
Subrequest method in upper case, such as 'GET', 'POST', 'PATCH', or 'DELETE'.


Example: DELETE
relative_urlstring
Relative resource identifier.


Example: /v2/ocamba/roles/viewer
Response status codes
Arrow
200 - OK
Arrow
Name
Description
error_counterinteger
Description goes here
parts[ batch-response-part ]

Batch Response
Name
Description
body
Can be any value - string, number, boolean, array or object.
codeinteger
HTTP response status code.


Example: 200
headersobject
HTTP response headers.
success_counterinteger
Description goes here


Example: 10
total_counterinteger
Description goes here


Example: 10
400 - Bad Request
Arrow
Name
Description
codeinteger
Http response status code.


Example: 400
messagestring
The human readable message that describes how to deal with error.


Example: The request body is not valid.
titlestring
The error title.


Example: Bad request.
trace_idstring
Error trace id.


Example: 99a84211-f73d-4ff8-acdf-eb3e06bb9d62
500 - Internal Server Error
Arrow
Name
Description
codeinteger
Http response status code.


Example: 500
messagestring
The human readable message that describes how to deal with error.


Example: Internal server error.
titlestring
The error title.


Example: Internal server error.
Request examples
Copied
Arrow
simple Arrow
  • simple
  • complex
  • abort_on_fail
  • with_headers
[
  {
    "method": "GET",
    "relative_url": "/members/10"
  },  
  {
    "method": "GET",
    "relative_url": "members/10/roles"
  }
]

[
  {
    "method": "POST",
    "relative_url": "/roles"
    "body": {
      "name": "viewer_new",
      "permissions": ["members.get","roles.get","countries.get","languages.get"]
    }
  },  
  {
    "method": "DELETE",
    "relative_url": "/roles/viewer"
  }
]  

[
  {
    "method": "POST",
    "relative_url": "/roles"
    "body": {
      "name": "viewer_new",
      "permissions": ["members.get","roles.get","countries.get","languages.get"]
    },
    "abort_on_fail": true
  },  
  {
    "method": "DELETE",
    "relative_url": "/roles/viewer"
  }
]   

[
  {
    "method": "POST",
    "relative_url": "/roles"
    "body": {
      "name": "viewer_new",
      "permissions": ["members.get","roles.get","countries.get","languages.get"]
    }
  },  
  {
    "method": "DELETE",
    "relative_url": "/roles/viewer",
    "headers": {
      "force-delete": "yes"
    }
  }
]
Response examples
Copied
Arrow
200 Arrow
  • 200
  • 400
  • 500
{
  "total_counter": 10,
  "success_counter": 10,
  "parts": [
    {
      "code": 200
    }
  ]
}

{
  "code": 400,
  "title": "Bad request.",
  "message": "The request body is not valid.",
  "trace_id": "99a84211-f73d-4ff8-acdf-eb3e06bb9d62"
}

{
  "code": 500,
  "title": "Internal server error.",
  "message": "Internal server error."
}