1. REST API for Unified Assurance Core
  2. Tasks
  3. Core
  4. API Batches

Run APIs in Batches

post

/api/core/Batch/execute

Runs the batch of API requests specified in the request body Actions array. At minimum, each object in the array requires the api and method properties to specify the endpoint and REST method.

Include any required parameters and request body properties for the specified endpoint in the data or dynamicData properties. You do not need to specify whether a parameter belongs in the path, query, or body. You can use data for properties with static values, or you can use dynamicData for properties with both static values and values that are defined dynamically based on responses to earlier requests in the same batch. You can use both data and dynamicData in the same object, or for simplicity, you can include all properties in dynamicData. As best practices, do not repeat the same property in both data and dynamicData, and put each nested array in only one location.

For example, the Update a Device endpoint requires:

  • An id parameter in the path. You can specify this in data or dynamicData if you know the event ID, or dynamicData to dynamically determine the event ID based on the response to an earlier request in the same batch.
  • A request body with the properties that you want to update from the deviceDevices schema. Specify properties with static values in data or dynamicData and specify properties with dynamic values in dynamicData. If, for example, you want to include dynamically defined and static values in the nested MetaData array, you can include the entire MetaData array, with both static and dynamic values, in dynamicData.
For endpoints without required parameters, such as Get Devices, you can use data or dynamicData to provide filtering and pagination query parameters. Oracle recommends using filtering and pagination for endpoints like Get Devices that could return many results. The example request body includes objects for the Get Broker Servers and Get Broker Services endpoints that use properties in data and dynamicData to limit and filter results. To include multiple filters with dynamic and static values, include the entire filters array, with both static and dynamic values, in dynamicData.

See the descriptions of each endpoint in this document for required and optional parameters.

You can optionally use the following properties to string requests together:

  • response: Defines local variables, with names that you determine, to store values from API response fields. Include these variables in the dynamicData properties of later actions in the same batch.
  • dynamicData: Defines request query, path, or body parameters with values that are dynamically supplied by the variables defined in earlier responses in the same batch.
  • forEach: Makes the same request (specified in the api and method properties) for each element in an array. Usually you define one Actions array item with a GET request to get a list of resources, then define another Actions array item that includes forEach to make the same PATCH, PUT, or DELETE request for each resource in the list. The API performs multiple actions based on the second object, so you do not have to write separate objects for each resource.
The example for this endpoint illustrates how to use a single batch request to get a server's ID based on its host FQDN, get the list of services for that server, and update the log level for each service in the list. For annotated examples, see Examples.

You can use batch files to automate configurations and reproduce settings in different environments. For example, if you want the same data in separate environments for testing or bug troubleshooting, you can use the same batch file to create the same resources in both places.

Request

There are no request parameters for this operation.

Supported Media Types
Request Body - application/json ()
Root Schema : schema
Type: object
Show Source
Nested Schema : Actions
Type: array
The array of objects with API requests defined in them.
Show Source
Nested Schema : items
Type: object
Show Source
  • The API endpoint to run a request against.
    Example: broker/services
  • data
    Parameters with static values to use in the request path, query, or body.
  • dynamicData
    Parameters with dynamic values to use in the path, query, or body. These parameters are dynamically defined as the batch is run. You use variables created in the response property of a previous request in the dynamicData of subsequent requests in the batch. For example, if a previous request in the batch saved a server ID returned in its response, you could use that server ID in the body, path, or query of the subsequent request.
  • forEach
    An object defining a loop over an array. For each item in the array variable referenced in the from property:
    1. Store the value in a new variable named in the varName property
    2. Run the API request, using the new variable, referenced in the dynamicData property.
  • The method of the API to call. Allowed values are:
    • create: For POST requests.
    • read: For GET requests.
    • update: For PATCH or PUT requests.
    • delete: For DELETE requests.
    Example: read
  • response
    The array of field-value pairs to populate with values from the API response. For example, you could save the server ID returned in the response of a request to get server details based on the web FQDN, and use the server ID in the dynamicData of a subsequent request in the batch.
Nested Schema : data
Type: object
Parameters with static values to use in the request path, query, or body.
Example:
{
    "limit":1,
    "filter":{
        "property":"ServerHostFQDN",
        "value":"host.example.com",
        "operator":"eq"
    }
}
Nested Schema : dynamicData
Type: object
Parameters with dynamic values to use in the path, query, or body. These parameters are dynamically defined as the batch is run. You use variables created in the response property of a previous request in the dynamicData of subsequent requests in the batch. For example, if a previous request in the batch saved a server ID returned in its response, you could use that server ID in the body, path, or query of the subsequent request.
Example:
{
    "filter":{
        "property":"ServerID",
        "value":"$ServerID",
        "operator":"eq"
    }
}
Nested Schema : forEach
Type: object
An object defining a loop over an array. For each item in the array variable referenced in the from property:
  1. Store the value in a new variable named in the varName property
  2. Run the API request, using the new variable, referenced in the dynamicData property.
Show Source
  • The name of a variable defined in the response property of a previous API request in the same batch. This variable contains the array to run the request on.
    Example: DeviceIDList
  • The name of a new variable to store the value from each entry in the array referenced in the from property. Use this variable in the dynamicData property for the current action. The value is updated dynamically as the loop works through each item in the array.
    Example: DeviceID
Nested Schema : response
Type: array
The array of field-value pairs to populate with values from the API response. For example, you could save the server ID returned in the response of a request to get server details based on the web FQDN, and use the server ID in the dynamicData of a subsequent request in the batch.
Show Source
Nested Schema : items
Type: object
Show Source
  • The name of the field from the response whose values should be stored in the variable. This must match a field in the response. For example, if the response contains a list of devices, and you want to save the device IDs to use in another request, use DeviceID.
    Example: DeviceID
  • The name of the variable to store response values in for use in later requests in the same batch. Choose a simple, logical name. For example, if the response contains a list of devices, and you want to save the device IDs to use in another request, you could call this DeviceIDList.
    Example: DeviceIDList
  • Allowed Values: [ "single", "array" ]
    Whether the variable contains a list of values (array) or a single value (single). For example, if the response contains a list of devices, and you want to save all of the device IDs to use in another request with a forEach loop, use array. If the response contains a single device, use single.
    Example: array
Back to Top

Response

Supported Media Types

200 Response

Successful operation
Body ()
Root Schema : schema
Match All
Show Source
Nested Schema : SuccessfulGetOperation
Type: object
The response body for a successful get operation.
Show Source
Nested Schema : type
Type: object
Show Source
Nested Schema : data
Type: array
Show Source
Nested Schema : coreBatchExecuteResponseBody
Type: object
Show Source
  • The API endpoint from which the response is returned.
    Example: /broker/services
  • The method of the API that was called.
    Example: read
  • request
    An object that contains the combined properties from both data and dynamicData that were sent in the request body. If data and dynamicData contain the same keys, the values are combined into an array. Any variables referenced in the request are replaced by their actual values in the response. In the example, ApplicationConfig came from data in the request, id came from dynamicData, and the value of id was dynamically updated from a variable to an actual value.
  • response
    The response object from the API.
Nested Schema : request
Type: object
An object that contains the combined properties from both data and dynamicData that were sent in the request body. If data and dynamicData contain the same keys, the values are combined into an array. Any variables referenced in the request are replaced by their actual values in the response. In the example, ApplicationConfig came from data in the request, id came from dynamicData, and the value of id was dynamically updated from a variable to an actual value.
Example:
{
    "ApplicationConfig":{
        "BrokerApplicationConfigTypeID":2,
        "BrokerApplicationConfigName":"LogLevel",
        "BrokerApplicationConfigValue":4,
        "Required":1
    },
    "id":1234
}
Nested Schema : response
Type: object
The response object from the API.
Show Source
Example:
{
    "success":true,
    "message":"Updated record",
    "data":{
        "ApplicationConfig":{
            "BrokerApplicationConfigTypeID":2,
            "BrokerApplicationConfigName":"LogLevel",
            "BrokerApplicationConfigValue":4,
            "Required":1
        },
        "id":1234
    }
}
Nested Schema : data
Type: object
The response body.
Example:
{
    "ApplicationConfig":{
        "BrokerApplicationConfigTypeID":2,
        "BrokerApplicationConfigName":"LogLevel",
        "BrokerApplicationConfigValue":4,
        "Required":1
    },
    "id":1234
}

Default Response

Failed operation
Body ()
Root Schema : schema
Type: object
Show Source
Nested Schema : errors
Type: array
The list of errors reported. Validation errors will be keyed by record field.
Show Source
Nested Schema : items
Type: object
An error.
Back to Top

Examples

The following examples show how to make API requests in batches. You create a JSON document to contain the requests and pass it to the core/Batch/execute endpoint as the body for a POST request.

You can submit a request using cURL or an API client. The following example uses cURL:

curl -X POST http://hostFQDN/api/core/Batch/execute -d @batchrequest.json

In the JSON document, you can string requests together to use data from one request in a subsequent request. You do this by saving data returned in a response as variables in the response parameter. You can then use these variables in the subsequent requests. For example, a single batch can contain:

  • A request that gets a resource's information based on filters, and saves the resource ID in a variable
  • A request that updates the resource using the ID from the variable

You can also use the forEach parameter to make the same request for each element in an array. For example, a single batch can contain:

  • A request that gets a list of resources and saves their IDs in an array
  • A request that updates each resource in the array.

Using the forEach parameter in the update request prevents you from having to write separate get and update requests for each resource.

Example of Updating Log Level for Broker Services

This example illustrates how to string together multiple API calls to update the log level of all broker services on a particular server. The different parts of the JSON object to use in the request body are shown seperately to explain each individually, then the final example combines them together in the Actions array at the root level of the JSON document.

In the JSON document used as the request body, add the following objects to the Actions array:

  • A Get Broker Servers request to get information about a server running on a specific host and create a variable to save the server ID returned in the response: 
    {
      "api": "broker/servers",
      "method": "read",
      "data": {
        "limit": 1,
        "filter": [
          {
            "property": "ServerHostFQDN",
            "value": "<HostFQDN>",
            "operator": "eq"
          }
        ]
      },
      "response": [
        {
          "varName": "ServerID",
          "fieldName": "ServerID",
          "varType": "single"
        }
      ]
    }

    The details of the JSON object for this call are:

    • api: Use the broker/servers endpoint.
    • method: Make a GET request (read).
    • data:
      • Apply the limit query parameter so that only one resource is returned.
      • Apply the filter query parameter so that only the resource with the specified host FQDN is returned.
    • response: Save the value of the ServerID field returned in the response as a variable called ServerID.
  • A Get Broker Services request to get a list of all services running on the server retrieved in the previous call and create a variable array to save the service IDs returned in the response:
        {
      "api": "broker/services",
      "method": "read",
      "dynamicData": {
        "filter": [
          {
            "property": "ServerID",
            "value": "$ServerID",
            "operator": "eq"
          }
        ]
      },
      "response": [
        {
          "varName": "ServiceIDs",
          "fieldName": "BrokerServiceID",
          "varType": "array"
        }
      ]
    }

    The details of the JSON object for this call are:

    • api: Use the broker/services endpoint.
    • method: Make a GET request (read).
    • dynamicData: Apply the ServerID query parameter, using the value saved in the $ServerID variable from the previous request.
    • response: Save the values of the BrokerServiceID fields returned in the response as entries in the ServiceIDs variable array.
  • An Update a Broker Service request to update each service that is running on the server, using the array of IDs retrieved in the previous call:
        {
      "forEach": {
        "from": "ServiceIDs",
        "varName": "ServiceID"
      },
      "api": "broker/services",
      "method": "update",
      "data": {
        "ApplicationConfig": [
          {
            "BrokerApplicationConfigTypeID": 2,
            "BrokerApplicationConfigName": "LogLevel",
            "BrokerApplicationConfigValue": "4",
            "Required": 1
          }
        ]
      },
      "dynamicData": {
        "id": "$ServiceID"
      }
    }

    The details of the JSON object for this call are:

    • forEach: Make the request for each entry in the ServiceIDs array created by the previous call, using the values from the ServiceID variable.
    • api: Use the broker/services endpoint.
    • method: Make a PUT request (update).
    • data: Update the specified fields.
    • dynamicData: Use the value of the ServiceID variable for each entry in the id path parameter.
Combining these objects together in the Actions array results in the following JSON document:
{    
  "Actions": [
    {
      "api": "broker/servers",
      "method": "read",
      "data": {
        "limit": 1,
        "filter": [
          {
            "property": "ServerHostFQDN",
            "value": "<HostFQDN>",
            "operator": "eq"
          }
        ]
      },
      "response": [
        {
          "varName": "ServerID",
          "fieldName": "ServerID",
          "varType": "single"
        }
      ]
    },
    {
      "api": "broker/services",
      "method": "read",
      "dynamicData": {
        "filter": [
          {
            "property": "ServerID",
            "value": "$ServerID",
            "operator": "eq"
          }
        ]
      },
      "response": [
        {
          "varName": "ServiceIDs",
          "fieldName": "BrokerServiceID",
          "varType": "array"
        }
      ]
    },
    {
      "forEach": {
        "from": "ServiceIDs",
        "varName": "ServiceID"
      },
      "api": "broker/services",
      "method": "update",
      "data": {
        "ApplicationConfig": [
          {
            "BrokerApplicationConfigTypeID": 2,
            "BrokerApplicationConfigName": "LogLevel",
            "BrokerApplicationConfigValue": "4",
            "Required": 1
          }
        ]
      },
      "dynamicData": {
        "id": "$ServiceID"
      }
    }
  ]
}

Example of the Response Body

The batch response body contains one item for each request in the data array.

Within each item, the request property contains all of the properties that were included in data and dynamicData in the request, with any variables replaced by their actual values. The response property contains the response body, including response message and data.

Note:

In this example, the response data objects have been shortened where indicated by ... for simplicity. The full response would include more properties in the data objects and a separate object for each service updated by the forEach parameter. See the documentation of the individual endpoints for a full list of response parameters. 
{
  "success": "true",
  "message": "Loaded 3 entries",
  "data": [
    {
      "api": "/broker/servers",
      "method": "read",
      "request": {
        "limit": 1,
        "filter": [
          {
            "property": "ServerHostFQDN",
            "value": "<HostFQDN>",
            "operator": "eq"
          }
        ]
      },
      "response": {
        "success": true,
        "message": "Loaded 1 entries",
        "data": [
          {
            "ServerID": "1",
            "PrimaryServerID": "2",
            "ServerPlatformName": "EXL8",
            ...           
          }  
        ]
      }
    },
    {
      "api": "/broker/services",
      "method": "read",
      "request": {
        "ServerID": "1"
          }
        ]
      },
      "response": {
        "success": true,
        "message": "Loaded 10 entries",
        "data": [
          {
            "BrokerServiceID": "1",
            "ServerID": "1",
            "ServerName": "example.com",
            ...           
          },  
          {
            "BrokerServiceID": "2",
            "ServerID": "1",
            "ServerName": "example.com",
            ...           
          },
          ...
        ]
      }
    },
    {
      "api": "/broker/services",
      "method": "update",
      "request": {
        "ApplicationConfig": [
            {
              "BrokerApplicationConfigTypeID": 2,
              "BrokerApplicationConfigName": "LogLevel",
              "BrokerApplicationConfigValue": "4",
              "Required": 1
            }
          ],
          "id": "1"
          },
      "response": {
        "success": true,
        "message": "Updated record",
        "data": [
          {
            "BrokerServiceID": "1",
            "ServerID": "1",
            "ServerName": "example.com",
            ...           
          }  
        ]
      }, 
      {
        "api": "/broker/services",
        "method": "update",
        "request": {
          "ApplicationConfig": [
              {
                "BrokerApplicationConfigTypeID": 2,
                "BrokerApplicationConfigName": "LogLevel",
                "BrokerApplicationConfigValue": "4",
                "Required": 1
              }
            ],
            "id": "2"
            },
        "response": {
          "success": true,
          "message": "Updated record",
          "data": [
            {
              "BrokerServiceID": "2",
              "ServerID": "1",
              "ServerName": "example.com",
              ...           
            }  
          ]
        },
      ...
    ]
}
Back to Top