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`¶
`requests:`
`id`	Give your request an ID
`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 variables for the future responses of the previous requests

The /batch endpoint contains a variables object, which serves definition purposes for the future references for the responses.

Example (use horizontal scroll to see full comments):

      {
"variables": {
  "username": "jdoe",
},
"requests": [
  {
    "id": "123",
    "method": "POST",
    "endpoint": "/user",
    "data": {
      "name": "{username}" <---- Reference to the "username" variable
    }
  },
  {
    "method": "POST",
    "endpoint": "/user/{123.user.id}/authentication", <--- Reference to the response to the previous request with an "id": "123" {<response-id>.user.id}.
    "data": {
      "type": "password",
      "position": 0,
      "secret": "test123"
    }
  }
]}

Whereas, the response to the previous request is the following:

      {
"id": "123",
"result": "success",
"status": 200,
"user": {
    "id": "12345678901234567",
    "name": "test"
      }

Allowed methods

`GET`	for reading data of an existing object; no request body is required
`POST`	for creating an object; requires a request body, specified in JSON format, that contains the values for properties of the object that is about to be created
`PATCH`	for modifying an existing object; requires a request body, specified in JSON format, that contains the values for properties of the object
`DELETE`	for removing an existing object; no request body is required

There is a list of URL parameters available for a specific method to be included within a path:

fields - for including the object fields in the query,

filter - narrows out the result with available additions:

in - include possible field values (separated with comma),

match - include a sequence of characters to be searched in field values,

eq - equal,

ne - not equal,

lt - less than,

le - less or equal,

gt - greater than,

ge - greater than or equal

blocked - filter blocked objects,

!blocked - filter unblocked objects,

isempty() - filter objects with empty values in specified fields, only applies to arrays (e.g., server.isnull()),

order,

offset,

limit,

debug - for showing statistics, database errors, etc,

total_count,

reveal - to see objects: active, removed, or all for both removed and un-removed.

An example of the request that shows a list of 10 users that have a role user with their id and name specified, sorted alphabetically by their names and shows a total count of users that match the given criteria: GET https://<fudo_address>/api/v2/user?fields=id,name&filter=role.eq(user)&order=name&limit=10&total_count

Possible responses

Code	Status
`200`	success	`OK`
`201`	success	`CREATED`
`400`	failure	`BAD REQUEST`; message examples: `Unrecognized endpoint`, `Request body is not allowed for this endpoint`
`401`	failure	`UNAUTHORIZED`
`404`	failure	`BAD REQUEST`; message example: `Object not found`

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 4 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": [
  {
    "id": "request0",
    "method": "GET",
    "endpoint": "/user",
    "params": {
      "filter": "name.eq(test)",
      "fields": "id,name"
    }
  },
  {
    "id": "request1",
    "method": "DELETE",
    "endpoint": "/user/{request0.user[0].id}",
    "params": {
      "fields": "name"
    }
  },
  {
    "id": "request2",
    "method": "POST",
    "endpoint": "/user",
    "data": {
      "name": "{request0.user[0].name}",
      "role": "user"
    }
  },
  {
    "id": "request3",
    "method": "POST",
    "endpoint": "/user/{request2.user.id}/authentication",
    "params": {
      "fields": "user_id"
    },
    "data": {
      "type": "password",
      "position": 0,
      "secret": "abcd.8"
    }
  }
]}

Response

      {
"result": "success",
"responses": [
  {
    "id": "request0",
    "result": "success",
    "status": 200,
    "user": [
      {
        "id": "2179742219647320079",
        "name": "test"
      }
    ]
  },
  {
    "id": "request1",
    "result": "success",
    "status": 200
  },
  {
    "id": "request2",
    "result": "success",
    "status": 201,
    "user": {
      "id": "2179742219647320080"
    }
  },
  {
    "id": "request3",
    "result": "success",
    "status": 201,
    "user_authentication_method": {
      "user_id": "2179742219647320080"
    }
  }
]}