FIWARE Batch Operations API

openapi: 3.2.0
info:
  title: Fiware Batch Operations API
  version: '1.0'
  description: 'Operations tagged Batch Operations across 2 of this provider''s published API definitions: fiware-ngsi-ld-openapi.yml, fiware-ngsiv2-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: http://orion.lab.fiware.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
      parameters:
      - name: Content-Type
        in: header
        required: true
        description: ''
        schema:
          type: string
      - name: options
        in: query
        required: false
        x-enum-elements:
        - name: keyValues
          description: ''
        description: Options dictionary
        schema:
          type: string
          enum:
          - keyValues
      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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRequest'
        required: true
    servers:
    - url: http://orion.lab.fiware.org/
  /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
      parameters:
      - name: Content-Type
        in: header
        required: true
        description: ''
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Limit the number of entities to be retrieved.
        schema:
          type: number
          format: double
      - name: offset
        in: query
        required: false
        description: Skip a number of records.
        schema:
          type: number
          format: double
      - name: orderBy
        in: query
        required: false
        description: 'Criteria for ordering results.

          See "Ordering Results" section for details.'
        schema:
          type: string
      - name: options
        in: query
        required: false
        x-enum-elements:
        - name: count
          description: ''
        - name: keyValues
          description: ''
        - name: values
          description: ''
        - name: unique
          description: ''
        description: Options dictionary
        schema:
          type: string
          enum:
          - count
          - keyValues
          - values
          - unique
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/QueryResponse'
              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: 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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
        required: true
    servers:
    - url: http://orion.lab.fiware.org/
  /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
      parameters:
      - name: Content-Type
        in: header
        required: true
        description: ''
        schema:
          type: string
      - name: options
        in: query
        required: false
        x-enum-elements:
        - name: keyValues
          description: ''
        description: Options dictionary
        schema:
          type: string
          enum:
          - keyValues
      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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotifyRequest'
        required: true
    servers:
    - url: http://orion.lab.fiware.org/
components:
  schemas:
    polygon:
      description: An array of linear rings
      type: array
      items:
        $ref: '#/components/schemas/linearRing'
    MultiPoint:
      type: object
      properties:
        type:
          type: string
          enum:
          - MultiPoint
        coordinates:
          $ref: '#/components/schemas/positionArray'
    positionArray:
      description: An array of positions
      type: array
      items:
        $ref: '#/components/schemas/position'
    observedAt:
      type: string
      format: date-time
    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'
    LineString:
      type: object
      properties:
        type:
          type: string
          enum:
          - LineString
        coordinates:
          $ref: '#/components/schemas/lineString'
    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'
    BatchOperationResult:
      type: object
      properties:
        success:
          type: array
          items:
            type: string
            format: uri
        error:
          type: array
          items:
            $ref: '#/components/schemas/BatchEntityError'
    Entity:
      allOf:
      - required:
        - id
        - type
      - $ref: '#/components/schemas/EntityFragment'
    createdAt:
      type: string
      format: date-time
    BatchEntityError:
      type: object
      properties:
        entityId:
          type: string
          format: uri
        error:
          $ref: '#/components/schemas/ProblemDetails'
    EntityList:
      type: array
      items:
        $ref: '#/components/schemas/Entity'
    datasetId:
      type: string
      format: uri
    Name:
      type: string
      pattern: ^((\d|[a-zA-Z]|_)+(:(\d|[a-zA-Z]|_)+)?(#\d+)?)$
      minLength: 1
      description: NGSI-LD Name
    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
    Polygon:
      type: object
      properties:
        type:
          type: string
          enum:
          - Polygon
        coordinates:
          $ref: '#/components/schemas/polygon'
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        detail:
          type: string
      required:
      - type
    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'
    linearRing:
      description: An array of four positions where the first equals the last
      allOf:
      - $ref: '#/components/schemas/positionArray'
      - minItems: 4
    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'
    lineString:
      description: An array of two or more positions
      allOf:
      - $ref: '#/components/schemas/positionArray'
      - minItems: 2
    modifiedAt:
      type: string
      format: date-time
    position:
      description: A single position
      type: array
      minItems: 2
      maxItems: 2
      items:
        type: number
      additionalProperties: false
    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'
    instanceId:
      type: string
      format: uri
    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'
    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
    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
    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
    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
externalDocs:
  description: Find out more about the ETSI ISG Context Information Management
  url: https://portal.etsi.org/tb.aspx?tbid=854&SubTB=854
x-refined-from:
- fiware-ngsi-ld-openapi.yml
- fiware-ngsiv2-openapi.yml