FIWARE Batch Operations API
The Batch Operations API from FIWARE — 7 operation(s) for batch operations.
OpenAPI Specification
openapi: 3.0.3
info:
description: This OAS file describes the NGSI-LD API defined by the ETSI ISG CIM group. This Cross-domain Context Information Management API allows to provide, consume and subscribe to context information in multiple scenarios and involving multiple stakeholders
version: latest
title: ETSI ISG CIM / NGSI-LD API Entry Point Batch Operations API
contact:
email: NGSI-LD@etsi.org
tags:
- name: Batch Operations
paths:
/entityOperations/create:
post:
description: Batch Entity creation
operationId: batchEntityCreation
tags:
- Batch Operations
requestBody:
required: true
content:
application/json;application/ld+json:
schema:
$ref: '#/components/schemas/EntityList'
responses:
'200':
description: Success
content:
application/json;application/ld+json:
schema:
$ref: '#/components/schemas/BatchOperationResult'
'400':
description: Bad request
content:
application/json;application/ld+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/entityOperations/update:
post:
description: Batch Entity update
operationId: batchEntityUpdate
tags:
- Batch Operations
parameters:
- name: options
in: query
required: false
schema:
type: string
enum:
- noOverwrite
requestBody:
required: true
content:
application/json;application/ld+json:
schema:
$ref: '#/components/schemas/EntityList'
responses:
'200':
description: Success
content:
application/json;application/ld+json:
schema:
$ref: '#/components/schemas/BatchOperationResult'
'400':
description: Bad request
content:
application/json;application/ld+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/entityOperations/upsert:
post:
description: Batch Entity upsert
operationId: batchEntityUpsert
tags:
- Batch Operations
parameters:
- name: options
in: query
required: false
schema:
type: string
enum:
- replace
- update
requestBody:
required: true
content:
application/json;application/ld+json:
schema:
$ref: '#/components/schemas/EntityList'
responses:
'200':
description: Success
content:
application/json;application/ld+json:
schema:
$ref: '#/components/schemas/BatchOperationResult'
'400':
description: Bad request
content:
application/json;application/ld+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/entityOperations/delete:
post:
description: Batch Entity delete
operationId: batchEntityDelete
tags:
- Batch Operations
requestBody:
required: true
content:
application/json;application/ld+json:
schema:
type: array
items:
type: string
format: uri
minItems: 1
responses:
'200':
description: Success
content:
application/json;application/ld+json:
schema:
$ref: '#/components/schemas/BatchOperationResult'
'400':
description: Bad request
content:
application/json;application/ld+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/v2/op/update:
post:
description: "This operation allows to create, update and/or delete several entities in a single batch operation.\nThe payload is an object with two properties:\n+ `actionType`, to specify the kind of update action to do: either `append`, `appendStrict`, `update`,\n `delete`, or `replace`.\n+ `entities`, an array of entities, each entity specified using the JSON entity representation format\n (described in the section \"JSON Entity Representation\").\nThis operation is split in as many individual operations as entities in the `entities` vector, so\nthe `actionType` is executed for each one of them. Depending on the `actionType`, a mapping with\nregular non-batch operations can be done:\n* `append`: maps to `POST /v2/entities` (if the entity does not already exist) or `POST /v2/entities/<id>/attrs`\n (if the entity already exists).\n* `appendStrict`: maps to `POST /v2/entities` (if the entity does not already exist) or\n `POST /v2/entities/<id>/attrs?options=append` (if the entity already exists).\n* `update`: maps to `PATCH /v2/entities/<id>/attrs`.\n* `delete`: maps to `DELETE /v2/entities/<id>/attrs/<attrName>` on every attribute included in the entity or\n to `DELETE /v2/entities/<id>` if no attribute were included in the entity.\n* `replace`: maps to `PUT /v2/entities/<id>/attrs`.\nResponse:\n* Successful operation uses 204 No Content.\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n more details."
summary: Update
tags:
- Batch Operations
operationId: Update
produces:
- application/json
parameters:
- name: Content-Type
in: header
required: true
type: string
description: ''
- name: body
in: body
required: true
description: ''
schema:
$ref: '#/definitions/UpdateRequest'
- name: options
in: query
required: false
enum:
- keyValues
x-enum-elements:
- name: keyValues
description: ''
type: string
description: Options dictionary
responses:
'204':
description: ''
x-unitTests:
- request:
method: POST
uri: /v2/op/update
headers:
Content-Type: application/json
body: '{ "actionType": "append", "entities": [ { "type": "Room", "id": "Bcn-Welt", "temperature": { "value": 21.7 }, "humidity": { "value": 60 } }, { "type": "Room", "id": "Mad_Aud", "temperature": { "value": 22.9 }, "humidity": { "value": 85 } } ]}'
expectedResponse:
x-allowExtraHeaders: true
x-bodyMatchMode: NONE
x-arrayOrderedMatching: false
x-arrayCheckCount: false
x-matchResponseSchema: true
headers: {}
x-testShouldPass: true
x-testEnabled: true
x-testName: Update1
x-testDescription: "This operation allows to create, update and/or delete several entities in a single batch operation.\nThe payload is an object with two properties:\n+ `actionType`, to specify the kind of update action to do: either `append`, `appendStrict`, `update`,\n `delete`, or `replace`.\n+ `entities`, an array of entities, each entity specified using the JSON entity representation format\n (described in the section \"JSON Entity Representation\").\nThis operation is split in as many individual operations as entities in the `entities` vector, so\nthe `actionType` is executed for each one of them. Depending on the `actionType`, a mapping with\nregular non-batch operations can be done:\n* `append`: maps to `POST /v2/entities` (if the entity does not already exist) or `POST /v2/entities/<id>/attrs`\n (if the entity already exists).\n* `appendStrict`: maps to `POST /v2/entities` (if the entity does not already exist) or\n `POST /v2/entities/<id>/attrs?options=append` (if the entity already exists).\n* `update`: maps to `PATCH /v2/entities/<id>/attrs`.\n* `delete`: maps to `DELETE /v2/entities/<id>/attrs/<attrName>` on every attribute included in the entity or\n to `DELETE /v2/entities/<id>` if no attribute were included in the entity.\n* `replace`: maps to `PUT /v2/entities/<id>/attrs`.\nResponse:\n* Successful operation uses 204 No Content.\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n more details."
x-operation-settings:
CollectParameters: false
AllowDynamicQueryParameters: false
AllowDynamicFormParameters: false
IsMultiContentStreaming: false
/v2/op/query:
post:
description: "The response payload is an Array containing one object per matching entity, or an empty array `[]` if \nno entities are found. The entities follow the JSON entity representation format\n(described in the section \"JSON Entity Representation\").\nThe payload may contain the following elements (all of them optional):\n+ `entities`: a list of entites to search for. Each element is represented by a JSON object with the\n following elements:\n + `id` or `idPattern`: Id or pattern of the affected entities. Both cannot be used at the same\n time, but one of them must be present.\n + `type` or `typePattern`: Type or type pattern of the entities to search for. Both cannot be used at\n the same time. If omitted, it means \"any entity type\".\n+ `attrs`: List of attributes to be provided (if not specified, all attributes).\n+ `expression`: an expression composed of `q`, `mq`, `georel`, `geometry` and `coords` (see \"List\n entities\" operation above about this field).\n+ `metadata`: a list of metadata names to include in the response.\n See \"Filtering out attributes and metadata\" section for more detail.\nResponse code:\n* Successful operation uses 200 OK\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n more details."
summary: Query
tags:
- Batch Operations
operationId: Query
produces:
- application/json
parameters:
- name: Content-Type
in: header
required: true
type: string
description: ''
- name: body
in: body
required: true
description: ''
schema:
$ref: '#/definitions/QueryRequest'
- name: limit
in: query
required: false
type: number
format: double
exclusiveMaximum: false
exclusiveMinimum: false
description: Limit the number of entities to be retrieved.
- name: offset
in: query
required: false
type: number
format: double
exclusiveMaximum: false
exclusiveMinimum: false
description: Skip a number of records.
- name: orderBy
in: query
required: false
type: string
description: 'Criteria for ordering results.
See "Ordering Results" section for details.'
- name: options
in: query
required: false
enum:
- count
- keyValues
- values
- unique
x-enum-elements:
- name: count
description: ''
- name: keyValues
description: ''
- name: values
description: ''
- name: unique
description: ''
type: string
description: Options dictionary
responses:
'200':
description: ''
schema:
type: array
items:
$ref: '#/definitions/QueryResponse'
examples:
application/json:
- type: Room
id: DC_S1-D41
temperature:
value: 35.6
type: Number
- type: Room
id: Boe-Idearium
temperature:
value: 22.5
type: Number
- type: Car
id: P-9873-K
temperature:
value: 40
type: Number
accuracy: 2
timestamp:
value: '2015-06-04T07:20:27.378Z'
type: DateTime
x-unitTests:
- request:
method: POST
uri: /v2/op/query?limit=10&offset=20&orderBy=temperature,!speed
headers:
Content-Type: application/json
body: '{ "entities": [ { "idPattern": ".*", "type": "Room" }, { "id": "Car", "type": "P-9873-K" } ], "attrs": [ "temperature", "humidity" ], "expression": { "q": "temperature>20" }, "metadata": [ "accuracy", "timestamp" ]}'
expectedResponse:
x-allowExtraHeaders: true
x-bodyMatchMode: RAW
x-arrayOrderedMatching: false
x-arrayCheckCount: false
x-matchResponseSchema: true
headers:
Content-Type: application/json
body: '[ { "type": "Room", "id": "DC_S1-D41", "temperature": { "value": 35.6, "type": "Number" } }, { "type": "Room", "id": "Boe-Idearium", "temperature": { "value": 22.5, "type": "Number" } }, { "type": "Car", "id": "P-9873-K", "temperature": { "value": 40, "type": "Number", "accuracy": 2, "timestamp": { "value": "2015-06-04T07:20:27.378Z", "type": "DateTime" } } }]'
x-testShouldPass: true
x-testEnabled: true
x-testName: Query1
x-testDescription: "The response payload is an Array containing one object per matching entity, or an empty array `[]` if \nno entities are found. The entities follow the JSON entity representation format\n(described in the section \"JSON Entity Representation\").\nThe payload may contain the following elements (all of them optional):\n+ `entities`: a list of entites to search for. Each element is represented by a JSON object with the\n following elements:\n + `id` or `idPattern`: Id or pattern of the affected entities. Both cannot be used at the same\n time, but one of them must be present.\n + `type` or `typePattern`: Type or type pattern of the entities to search for. Both cannot be used at\n the same time. If omitted, it means \"any entity type\".\n+ `attrs`: List of attributes to be provided (if not specified, all attributes).\n+ `expression`: an expression composed of `q`, `mq`, `georel`, `geometry` and `coords` (see \"List\n entities\" operation above about this field).\n+ `metadata`: a list of metadata names to include in the response.\n See \"Filtering out attributes and metadata\" section for more detail.\nResponse code:\n* Successful operation uses 200 OK\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n more details."
x-operation-settings:
CollectParameters: false
AllowDynamicQueryParameters: false
AllowDynamicFormParameters: false
IsMultiContentStreaming: false
/v2/op/notify:
post:
description: "This operation is intended to consume a notification payload so that all the entity data included by such notification is persisted, overwriting if necessary.\nThis operation is useful when one NGSIv2 endpoint is subscribed to another NGSIv2 endpoint (federation scenarios). \nThe request payload must be an NGSIv2 notification payload. \nThe behaviour must be exactly the same as `POST /v2/op/update` with `actionType` equal to `append`.\nResponse code:\n* Successful operation uses 200 OK\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n more details."
summary: Notify
tags:
- Batch Operations
operationId: Notify
produces:
- application/json
parameters:
- name: Content-Type
in: header
required: true
type: string
description: ''
- name: body
in: body
required: true
description: ''
schema:
$ref: '#/definitions/NotifyRequest'
- name: options
in: query
required: false
enum:
- keyValues
x-enum-elements:
- name: keyValues
description: ''
type: string
description: Options dictionary
responses:
'200':
description: ''
x-unitTests:
- request:
method: POST
uri: /v2/op/notify
headers:
Content-Type: application/json
body: '{ "subscriptionId": "5aeb0ee97d4ef10a12a0262f", "data": [{ "type": "Room", "id": "DC_S1-D41", "temperature": { "value": 35.6, "type": "Number" } }, { "type": "Room", "id": "Boe-Idearium", "temperature": { "value": 22.5, "type": "Number" } }]}'
expectedResponse:
x-allowExtraHeaders: true
x-bodyMatchMode: NONE
x-arrayOrderedMatching: false
x-arrayCheckCount: false
x-matchResponseSchema: true
headers:
Content-Type: application/json
x-testShouldPass: true
x-testEnabled: true
x-testName: Notify1
x-testDescription: "This operation is intended to consume a notification payload so that all the entity data included by such notification is persisted, overwriting if necessary.\nThis operation is useful when one NGSIv2 endpoint is subscribed to another NGSIv2 endpoint (federation scenarios). \nThe request payload must be an NGSIv2 notification payload. \nThe behaviour must be exactly the same as `POST /v2/op/update` with `actionType` equal to `append`.\nResponse code:\n* Successful operation uses 200 OK\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n more details."
x-operation-settings:
CollectParameters: false
AllowDynamicQueryParameters: false
AllowDynamicFormParameters: false
IsMultiContentStreaming: false
components:
schemas:
Entity:
allOf:
- required:
- id
- type
- $ref: '#/components/schemas/EntityFragment'
positionArray:
description: An array of positions
type: array
items:
$ref: '#/components/schemas/position'
LineString:
type: object
properties:
type:
type: string
enum:
- LineString
coordinates:
$ref: '#/components/schemas/lineString'
MultiLineString:
type: object
properties:
type:
type: string
enum:
- MultiLineString
coordinates:
type: array
items:
$ref: '#/components/schemas/lineString'
Point:
type: object
properties:
type:
type: string
enum:
- Point
coordinates:
$ref: '#/components/schemas/position'
Name:
type: string
pattern: ^((\d|[a-zA-Z]|_)+(:(\d|[a-zA-Z]|_)+)?(#\d+)?)$
minLength: 1
description: NGSI-LD Name
Relationship:
type: object
properties:
type:
type: string
enum:
- Relationship
object:
type: string
format: uri
observedAt:
$ref: '#/components/schemas/observedAt'
createdAt:
$ref: '#/components/schemas/createdAt'
modifiedAt:
$ref: '#/components/schemas/modifiedAt'
datasetId:
$ref: '#/components/schemas/datasetId'
instanceId:
$ref: '#/components/schemas/instanceId'
required:
- type
- object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/Property'
- $ref: '#/components/schemas/Relationship'
BatchOperationResult:
type: object
properties:
success:
type: array
items:
type: string
format: uri
error:
type: array
items:
$ref: '#/components/schemas/BatchEntityError'
Property:
type: object
properties:
type:
type: string
enum:
- Property
value:
oneOf:
- string
- number
- boolean
- array
- object
observedAt:
$ref: '#/components/schemas/observedAt'
createdAt:
$ref: '#/components/schemas/createdAt'
modifiedAt:
$ref: '#/components/schemas/modifiedAt'
datasetId:
$ref: '#/components/schemas/datasetId'
instanceId:
$ref: '#/components/schemas/instanceId'
required:
- type
- value
additionalProperties:
oneOf:
- $ref: '#/components/schemas/Property'
- $ref: '#/components/schemas/Relationship'
modifiedAt:
type: string
format: date-time
Polygon:
type: object
properties:
type:
type: string
enum:
- Polygon
coordinates:
$ref: '#/components/schemas/polygon'
EntityFragment:
type: object
properties:
'@context':
$ref: '#/components/schemas/LdContext'
location:
$ref: '#/components/schemas/GeoProperty'
observationSpace:
$ref: '#/components/schemas/GeoProperty'
operationSpace:
$ref: '#/components/schemas/GeoProperty'
id:
type: string
format: uri
type:
$ref: '#/components/schemas/Name'
createdAt:
$ref: '#/components/schemas/createdAt'
modifiedAt:
$ref: '#/components/schemas/modifiedAt'
additionalProperties:
oneOf:
- $ref: '#/components/schemas/Property'
- $ref: '#/components/schemas/Relationship'
- $ref: '#/components/schemas/GeoProperty'
position:
description: A single position
type: array
minItems: 2
maxItems: 2
items:
type: number
additionalProperties: false
BatchEntityError:
type: object
properties:
entityId:
type: string
format: uri
error:
$ref: '#/components/schemas/ProblemDetails'
ProblemDetails:
type: object
properties:
type:
type: string
format: uri
title:
type: string
detail:
type: string
required:
- type
linearRing:
description: An array of four positions where the first equals the last
allOf:
- $ref: '#/components/schemas/positionArray'
- minItems: 4
MultiPoint:
type: object
properties:
type:
type: string
enum:
- MultiPoint
coordinates:
$ref: '#/components/schemas/positionArray'
datasetId:
type: string
format: uri
lineString:
description: An array of two or more positions
allOf:
- $ref: '#/components/schemas/positionArray'
- minItems: 2
EntityList:
type: array
items:
$ref: '#/components/schemas/Entity'
polygon:
description: An array of linear rings
type: array
items:
$ref: '#/components/schemas/linearRing'
GeoProperty:
type: object
properties:
type:
type: string
enum:
- GeoProperty
value:
$ref: '#/components/schemas/Geometry'
observedAt:
$ref: '#/components/schemas/observedAt'
createdAt:
$ref: '#/components/schemas/createdAt'
modifiedAt:
$ref: '#/components/schemas/modifiedAt'
datasetId:
$ref: '#/components/schemas/datasetId'
instanceId:
$ref: '#/components/schemas/instanceId'
required:
- type
- value
additionalProperties:
oneOf:
- $ref: '#/components/schemas/Property'
- $ref: '#/components/schemas/Relationship'
instanceId:
type: string
format: uri
observedAt:
type: string
format: date-time
MultiPolygon:
type: object
properties:
type:
type: string
enum:
- MultiPolygon
coordinates:
type: array
items:
$ref: '#/components/schemas/polygon'
LdContext:
oneOf:
- type: object
- type: string
format: uri
- type: array
minItems: 1
items:
oneOf:
- type: string
format: uri
- type: object
Geometry:
description: ' Avalid GeoJSON geometry object'
oneOf:
- $ref: '#/components/schemas/Point'
- $ref: '#/components/schemas/MultiPoint'
- $ref: '#/components/schemas/Polygon'
- $ref: '#/components/schemas/LineString'
- $ref: '#/components/schemas/MultiLineString'
- $ref: '#/components/schemas/MultiPolygon'
createdAt:
type: string
format: date-time
definitions:
NotifyRequest:
title: Notify request
example:
subscriptionId: 5aeb0ee97d4ef10a12a0262f
data:
- type: Room
id: DC_S1-D41
temperature:
value: 35.6
type: Number
- type: Room
id: Boe-Idearium
temperature:
value: 22.5
type: Number
type: object
properties:
subscriptionId:
description: ''
example: 5aeb0ee97d4ef10a12a0262f
type: string
data:
description: ''
example:
- type: Room
id: DC_S1-D41
temperature:
value: 35.6
type: Number
- type: Room
id: Boe-Idearium
temperature:
value: 22.5
type: Number
type: array
items:
type: object
required:
- subscriptionId
- data
QueryRequest:
title: Query request
example:
entities:
- idPattern: .*
type: Room
- id: Car
type: P-9873-K
attrs:
- temperature
- humidity
expression:
q: temperature>20
metadata:
- accuracy
- timestamp
type: object
properties:
entities:
description: ''
example:
- idPattern: .*
type: Room
- id: Car
type: P-9873-K
type: array
items:
type: object
attrs:
description: ''
example:
- temperature
- humidity
type: array
items:
type: string
expression:
description: ''
example:
q: temperature>20
type: object
metadata:
description: ''
example:
- accuracy
- timestamp
type: array
items:
type: string
required:
- entities
- attrs
- expression
- metadata
QueryResponse:
title: Query response
example:
type: Room
id: DC_S1-D41
temperature:
value: 35.6
type: Number
type: object
properties:
type:
description: ''
example: Room
type: string
id:
description: ''
example: DC_S1-D41
type: string
temperature:
description: ''
example:
value: 35.6
type: Number
type: object
required:
- type
- id
- temperature
UpdateRequest:
title: Update request
example:
actionType: append
entities:
- type: Room
id: Bcn-Welt
temperature:
value: 21.7
humidity:
value: 60
- type: Room
id: Mad_Aud
temperature:
value: 22.9
humidity:
value: 85
type: object
properties:
actionType:
description: ''
example: append
type: string
entities:
description: ''
example:
- type: Room
id: Bcn-Welt
temperature:
value: 21.7
humidity:
value: 60
- type: Room
id: Mad_Aud
temperature:
value: 22.9
humidity:
value: 85
type: array
items:
type: object
required:
- actionType
- entities
externalDocs:
description: Find out more about the ETSI ISG Context Information Management
url: https://portal.etsi.org/tb.aspx?tbid=854&SubTB=854