API v2: Batch requests¶
Fudo Enterprise allows using its API for sending a batch request by which an administrator can perform nested operations with different methods. Creating an account and assigning an authentication method to it or defining 100 servers in one request is possible with an endpoint /batch
.
Note
The /batch
endpoint is available to use on objects of API v2 only.
Data structures¶
Batch operation element | Possible values / Request variant | Description |
---|---|---|
atomic |
true , false |
Set a global value atomic=true to ensure that all requests within a batch operation are executed. In case of failure of any request, the entire operation will be reverted. |
variables |
Define variables to facilitate future referencing of responses. | |
requests: |
Remember to give your request a unique ID that consist of characters matching any single character from the following set: lowercase letters (a-z), uppercase letters (A-Z), digits (0-9), hyphens (-), colons (:), or underscores (_). | |
method |
Use one of the available methods per request. | |
endpoint |
Use one of the available endpoints per request. | |
params |
Include optional URL parameters. | |
data |
Include optional attributes values or variables for the future responses of the previous requests. | |
atomic |
Override global atomic=true with a local atomic=false . |
Note
To check allowed methods, available URL parameters and possible responses please refer to the API overview section.
Creating a batch operation¶
Request
Method | POST
|
Path | /api/v2/batch
|
Headers | Content-Type: Application/JSON
|
Body | BatchModel
|
Example of a batch operation that contains four requests:
request0
returns a list of users’ IDs and names, where the user’sname
==test
,request1
deletes the first user that was on the list of therequest0
’s response,request2
creates a new user withname
of the first user from therequest0
’s response and assigns a roleuser
to it,request3
assignspassword
as an authentication method for the user that was created in therequest2
Example request
{
"requests": {
"request0": {
"method": "GET",
"endpoint": "/user",
"params": {
"filter": "name.eq(test)",
"fields": "id,name"
}
},
"request1": {
"method": "DELETE",
"endpoint": "/user/{responses.request0.user[0].id}"
},
"request2": {
"method": "POST",
"endpoint": "/user",
"data": {
"name": "{responses.request0.user[0].name}",
"role": "user"
}
},
"request3": {
"method": "POST",
"endpoint": "/user/{responses.request2.user.id}/authentication",
"data": {
"type": "password",
"position": 0,
"secret": "abcd.8"
}
}
}
}
Response
{
"result": "success",
"responses": {
"request0": {
"result": "success",
"status-code": 200,
"user": [
{
"id": "8511803295730237462",
"name": "test"
}
]
},
"request1": {
"result": "success",
"status-code": 200
},
"request2": {
"result": "success",
"status-code": 201,
"user": {
"id": "8511803295730237463"
}
},
"request3": {
"result": "success",
"status-code": 201,
"user_authentication_method": {
"id": "8511803295730237489"
}
}
}
}
Creating a batch operation using variable¶
The example below demonstrates a batch operation with "username": "jdoe"
variable defined. This variable was used to dynamically populate the name
field in the user_1
request. Next, the user_auth
request includes {responses.user_1.user.id}
({responses.<response-id>.user.id}
), which is a placeholder that will be replaced with the actual id
value generated from the response of the user_1
request.
Request
{
"variables": {
"username": "jdoe"
},
"requests": {
"user_1": {
"method": "POST",
"endpoint": "/user",
"data": {
"name": "{variables.username}"
}
},
"user_auth": {
"method": "POST",
"endpoint": "/user/{responses.user_1.user.id}/authentication",
"data": {
"type": "password",
"position": 0,
"secret": "test123"
}
}
}
}
Response
{
"result": "success",
"responses": {
"user_1": {
"result": "success",
"status-code": 201,
"user": {
"id": "8511803295730237446"
}
},
"user_auth": {
"result": "success",
"status-code": 201,
"user_authentication_method": {
"id": "8511803295730237442"
}
}
}
}
Atomic functionality¶
The example below demonstrates a batch operation that includes two requests (user0
and user1
) for creating two users, where user0
request has invalid value (not_defined
) set for the role
attribute. While the global atomic
function is enabled for the batch operation, it is disabled solely for the user0
request. As a result, only user from the user1
request will be created.
Example request
{
"atomic": true,
"variables": {
"user_name_0": "jdoe",
"user_name_1": "jsmith"
},
"requests": {
"user0": {
"method": "POST",
"endpoint": "/user",
"atomic": false,
"data": {
"name": "{variables.user_name_0}",
"role": "not_defined"
}
},
"user1": {
"method": "POST",
"endpoint": "/user",
"data": {
"name": "{variables.user_name_1}",
"role": "operator"
}
}
}
}
Response
{
"result": "success",
"responses": {
"user0": {
"result": "failure",
"status-code": 400,
"message": "Invalid value of attribute role: 'not_defined'
(expected values=[ 'admin', 'operator', 'service', 'superadmin', 'user' ]).",
"failing_attributes": [
"role"
]
},
"user1": {
"result": "success",
"status-code": 201,
"user": {
"id": "8511803295730237444"
}
}
}
}