JSON Batch Requests

Standard SensorThings API v1.0 and v1.1 only supports multipart batch requests adapted from OData Version 4.0 Part 1: Protocol - 11.7.

This extension allows JSON batch requests adapted from OData Version 4.01. Part 1: Protocol - 11.7 and OData JSON Format Version 4.01 - 19.

A Batch Request header example:

    POST /v1.1/$batch HTTP/1.1
    Host: example.org
    Content-Type: application/json
    Content-Length: ###

    <JSON Batch request body>

Batch request body example

The following example shows a Batch Request that contains the following operations in the order listed:

• A query request
• Change Set that contains the following 2 requests:
  • Insert entity (with id 1)
  • Update request (with id 2)
• A second query request

{
  "requests": [
    {
      "id": "0",
      "method": "get",
      "url": "Things(1)"
    },
    {
      "id": "1",
      "atomicityGroup": "group1",
      "method": "post",
      "url": "Things",
      "body": <JSON representation of a new Thing>
    },
    {
      "id": "2",
      "atomicityGroup": "group1",
      "method": "patch",
      "url": "Things(1)",
      "body": <JSON representation of Thing(1)>
    },
    {
      "id": "3",
      "method": "get",
      "url": "Things(3)"
    }
  ]
}

Referencing new entities in a change set example

Actions can reference entities previously created or fetched. To make a created entity referenceable, the POST that creates the entity must have a id property, the content of which must be a string limited to the characters a-zA-Z0-9_.:,;-. Subsequent requests in the same change set can now use the value of this property, prefixed with a $, in places where the ID of the created entity is required.

Example: A Batch Request that containing a single change set that contains the following requests:

1. Insert a new Sensor entity (with id sensor1)
2. Insert a new Datastream entity, referencing the previously created Sensor entity as “$sensor1”.

{
  "requests": [
    {
      "id": "sensor1",
      "atomicityGroup": "group1",
      "method": "post",
      "url": "Sensors",
      "body": {
		  "name": "DS18B20",
		  "description": "DS18B20 is an air temperature sensor",
		  "encodingType": "application/pdf",
		  "metadata": "http://datasheets.maxim-ic.com/en/ds/DS18B20.pdf"
		}
    },
    {
      "id": "2",
      "atomicityGroup": "group1",
      "method": "post",
      "url": "Things(5)/Datastreams",
      "body": {
		  "name": "Temperature Thing 5",
		  "description": "The temperature of thing 5",
		  "ObservedProperty": {"@iot.id": 12},
		  "Sensor": {"@iot.id": "$sensor1"}
		}
    }
  ]
}

Batch-processing response

Example referencing the first batch request example above, assume all the requests except the final query request succeed. In this case the response would be:

{
  "responses": [
    {
      "id": "0",
      "status": 200,
      "body": <JSON representation of the Thing entity with id = 1>
    },
    {
      "id": "1",
      "status": 201,
      "body": <JSON representation of a new Thing entity>,
      "location": "http://example.org/v1.1/Things(99)"
    },
    {
      "id": "2",
      "status": 204
    },
    {
      "id": "3",
      "status": 404,
      "body": <Error message>
    }
  ]
}

Advanced Features

Non-unique request ids

Request id values do not have to be unique. When a back-reference is resolved, the result of the latest, successful request with a matching id is used.

Back-references to GET requests

In contrast to OData, this exension allows back-references to GET requests in the same atomicityGroup. If the result of the GET is a single entity, this entity is used for the reference, as if this entity was created by a POST. If the result of the GET is an entity set, the first entity of the set is used.

Skipping requests in a batch

Requests in a batch can be skipped using the if property. The value of if is a reference to a preceding request, optionally prefixed with not .

An example, creating an ObservedProperty only if no ObservedProperty with a name Temperature already exists:

{
    "requests": [
        {
            "id": "op_Temperature",
            "atomicityGroup": "group1",
            "method": "get",
            "url": "ObservedProperties?$select=id&$filter=name eq 'Temperature'"
        },
        {
            "id": "op_Temperature",
            "if": "not $op_Temperature",
            "atomicityGroup": "group1",
            "method": "post",
            "url": "ObservedProperties",
            "body": {
                "name": "Temperature",
                "description": "Temperature",
                "definition": "http://dd.eionet.europa.eu/vocabulary/aq/meteoparameter/54"
            }
        }
    ]
}

Further requests in the same atomicityGroup can reference $op_Temperature, regardless of if it already existed, or was created by the batch request.

Conformance Class

The conformance class this extension must register in the SensorThings (v1.1 and up) index document is:

https://fraunhoferiosb.github.io/FROST-Server/extensions/JsonBatchRequest.html