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

BatchModel

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’s name == test,
• request1 deletes the first user that was on the list of the request0’s response,
• request2 creates a new user with name of the first user from the request0’s response and assigns a role user to it,
• request3 assigns password as an authentication method for the user that was created in the request2

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"
            }
        }
    }
}