Commit 1dff2a9f authored by daniel-gonzalez-sanchez's avatar daniel-gonzalez-sanchez
Browse files

Updating NGSI-LD OAS v1.8.1 operations already considered in v1.7.1: 1)... 

Updating NGSI-LD OAS v1.8.1 operations already considered in v1.7.1: 1) Including new query parameters, some descriptions, and headers for GET operations within the following endpoints: /entities, /entities/{entityId}, /temporal/entities, and /temporal/entities/{entityId}; 2) Updating and including the definition of the new/updated query parameters within the Parameters section of the NGSI-LD OAS; 3) Including error code 504 GatewayTimeout instead of 503 ServiceUnavailable for JSON-LD Context Access Points within the DELETE /jsonldContext/{contextId} operation; 4) Including GeoJSON FeatureCollection as return data type within the HTTP 200 response body of POST /entityOperations/query operation.
parent c2b6a6ae

ngsi-ld-api.yaml

+123 −7
Original line number Diff line number Diff line
@@ -101,6 +101,8 @@ paths: 
        - $ref: '#/components/parameters/Query.type'

        - $ref: '#/components/parameters/Query.idPattern'

        - $ref: '#/components/parameters/Query.attrs'

        - $ref: '#/components/parameters/Query.pick'

        - $ref: '#/components/parameters/Query.omit'

        - $ref: '#/components/parameters/Query.q'

        - $ref: '#/components/parameters/Query.csf'

        - $ref: '#/components/parameters/Query.geometry'
@@ -110,6 +112,11 @@ paths: 
        - $ref: '#/components/parameters/Query.geometryProperty'

        - $ref: '#/components/parameters/Query.lang'

        - $ref: '#/components/parameters/Query.scopeQ'

        - $ref: '#/components/parameters/Query.containedBy'

        - $ref: '#/components/parameters/Query.join'

        - $ref: '#/components/parameters/Query.joinLevel'

        - $ref: '#/components/parameters/Query.datasetId'

        - $ref: '#/components/parameters/Query.entityMap'

        - $ref: '#/components/parameters/Query.limit'

        - $ref: '#/components/parameters/Query.count'

        - $ref: '#/components/parameters/Query.options.entities'
@@ -126,7 +133,12 @@ paths: 


            If the Accept Header indicates that the Entities are to be rendered as GeoJSON, a response body

            containing the query result as GeoJSON FeatureCollection is returned.



            If an EntityMap has been requested, the HTTP response shall include an "NGSILDEntityMap" HTTP 

            header that contains the resource URI of the EntityMap resource used in the operation.

          headers:

            NGSILD-EntityMap:

              $ref: '#/components/headers/NGSILD-EntityMap'

            NGSILD-Results-Count:

              $ref: '#/components/headers/NGSILD-Results-Count'

            NGSILD-Tenant:
@@ -182,8 +194,15 @@ paths: 
        # Query params

        - $ref: '#/components/parameters/Query.type'

        - $ref: '#/components/parameters/Query.attrs'

        - $ref: '#/components/parameters/Query.pick'

        - $ref: '#/components/parameters/Query.omit'

        - $ref: '#/components/parameters/Query.geometryProperty'

        - $ref: '#/components/parameters/Query.lang'

        - $ref: '#/components/parameters/Query.containedBy'

        - $ref: '#/components/parameters/Query.join'

        - $ref: '#/components/parameters/Query.joinLevel'

        - $ref: '#/components/parameters/Query.datasetId'

        - $ref: '#/components/parameters/Query.entityMap'

        - $ref: '#/components/parameters/Query.options.entities'

        # Local Query param

        - $ref: '#/components/parameters/Query.local'
@@ -197,7 +216,12 @@ paths: 
            Attributes, unless the Accept Header indicates that the Entity is to be rendered as GeoJSON.



            If the Accept Header indicates that the Entity is to be rendered as GeoJSON, a GeoJSON Feature is returned.

            

            If an EntityMap has been requested, the HTTP response shall include an "NGSILDEntityMap" HTTP header that 

            contains the resource URI of the EntityMap resource used in the operation.

          headers:

            NGSILD-EntityMap:

              $ref: '#/components/headers/NGSILD-EntityMap'

            NGSILD-Tenant:

              $ref: '#/components/headers/NGSILD-Tenant'

            NGSILD-Warning:
@@ -1829,6 +1853,8 @@ paths: 
        - $ref: '#/components/parameters/Query.type'

        - $ref: '#/components/parameters/Query.idPattern'

        - $ref: '#/components/parameters/Query.attrs'

        - $ref: '#/components/parameters/Query.pick'

        - $ref: '#/components/parameters/Query.omit'

        - $ref: '#/components/parameters/Query.q'

        - $ref: '#/components/parameters/Query.csf'

        - $ref: '#/components/parameters/Query.geometry'
@@ -1844,6 +1870,7 @@ paths: 
        - $ref: '#/components/parameters/Query.aggrMethods'

        - $ref: '#/components/parameters/Query.aggrPeriodDuration'

        - $ref: '#/components/parameters/Query.scopeQ'

        - $ref: '#/components/parameters/Query.datasetId'

        - $ref: '#/components/parameters/Query.limit'

        - $ref: '#/components/parameters/Query.count'

        - $ref: '#/components/parameters/Query.options.temporal'
@@ -1906,6 +1933,8 @@ paths: 
        - $ref: '#/components/parameters/Path.entityId'

        # Query params

        - $ref: '#/components/parameters/Query.attrs'

        - $ref: '#/components/parameters/Query.pick'

        - $ref: '#/components/parameters/Query.omit'

        - $ref: '#/components/parameters/Query.timeproperty'

        - $ref: '#/components/parameters/Query.timerel'

        - $ref: '#/components/parameters/Query.timeAt'
@@ -1914,6 +1943,7 @@ paths: 
        - $ref: '#/components/parameters/Query.lang'

        - $ref: '#/components/parameters/Query.aggrMethods'

        - $ref: '#/components/parameters/Query.aggrPeriodDuration'

        - $ref: '#/components/parameters/Query.datasetId'

        - $ref: '#/components/parameters/Query.options.temporal'

        - $ref: '#/components/parameters/Query.options.sysAttrs'

        # Local Query param
@@ -2647,10 +2677,10 @@ paths: 
            @context identifier not known to the

            system, see clause 6.3.2. 

          $ref: '#/components/responses/NotFound'

        '503':

        '504':

          description: |

            It is used when re-downloading fails.

          $ref: '#/components/responses/ServiceUnavailable' 

          $ref: '#/components/responses/GatewayTimeout' 



components:

  headers:
@@ -2659,6 +2689,13 @@ components: 
        Contains the resource URI of the created entity resource.

      schema:

        type: string

    NGSILD-EntityMap:

      description: |

        If present, the EntityMap supplied is used for determining the set of Entities requested during the query operation. 

        The location of the EntityMap used in the query/retrieval operation is returned in the response.

      schema:

        type: string

        format: uri

    NGSILD-Results-Count:

      description: |

        6.3.13 Counting number of results. The total number of matching results (e.g. number of Entities) is returned.
@@ -2808,6 +2845,22 @@ components: 
        List of Attributes to be matched by the Entity and included in the response. If the Entity does not

        have any of the Attributes in attrs, then a 404 Not Found shall be retrieved. If attrs is not

        specified, no matching is performed and all Attributes related to the Entity shall be retrieved.



        A synonym for a combination of the pick and q parameters. Deprecated

        Each String is an Attribute (Property or Relationship) name.

      style: form

      explode: false

      schema:

        type: array

        items:

          type: string

      required: false

    Query.containedBy:

      name: containedBy

      in: query

      description: |

       List of entity ids which have previously been encountered whilst retrieving the 

       Entity Graph. Only applicable if joinLevel is present.

      style: form

      explode: false

      schema:
@@ -2856,10 +2909,16 @@ components: 
      name: datasetId

      in: query

      description: |

        Specifies the datasetId of the dataset to be deleted.

        Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute as per clause 4.5.5, 

        or the datasetId of the dataset to be deleted.

      style: form

      explode: true

      schema:

        oneOf:

          - type: string

            format: uri

          - type: array

            items: 

              type: string

              format: uri

      required: false
@@ -2896,6 +2955,15 @@ components: 
        type: string

        format: date-time

      required: false

    Query.entityMap:

      name: details

      in: query

      description: If true, the location of the EntityMap used in the operation is returned in the response.

      style: form

      explode: true

      schema:

        type: boolean

      required: false

    Query.id:

      name: id

      in: query
@@ -2987,6 +3055,26 @@ components: 
          - type: string

            pattern: ^near;((maxDistance==\\d+)|(minDistance==\\d+))$ 

      required: false

    Query.join:

      name: join

      in: query

      description: |

        The type of Linked Entity retrieval to apply (see clause 4.5.23). Allowed values: "flat", "inline", "@none".

      style: form

      explode: true

      schema:

        type: string

      required: false

    Query.joinLevel:

      name: joinLevel

      in: query

      description: |

        Depth of Linked Entity retrieval to apply. Only applicable if join parameter is present.

      style: form

      explode: true

      schema:

        type: integer

      required: false

    Query.kind:

      name: kind

      in: query
@@ -3057,6 +3145,19 @@ components: 
        type: string

        format: date-time

      required: false

    Query.omit:

      name: omit

      in: query

      description: |

        Each String is an Entity member ("id", "type", "scope" or a projected Attribute name). 

        When defined, the listed Entity members are removed from each Entity within the payload.

      style: form

      explode: false

      schema:

        type: array

        items:

          type: string

      required: false

    Query.options.entities:

      name: options

      in: query
@@ -3109,6 +3210,20 @@ components: 
        items:

          $ref: '#/components/schemas/options.upsert'

      required: false

    Query.pick:

      name: pick

      in: query

      description: |

        Each String is an Entity member ("id", "type", "scope" or a projected Attribute name).

        When defined, every Entity within the payload body is reduced down to only contain 

        the listed Entity members.

      style: form

      explode: false

      schema:

        type: array

        items:

          type: string

      required: false

    Query.q:

      name: q

      in: query
@@ -3186,7 +3301,8 @@ components: 
      name: type

      in: query

      description: |

        Selection of Entity Types as per clause 4.17.

        Selection of Entity Types as per clause 4.17. "*" is also allowed as a value and local is 

        implicitly set to true and shall not be explicitly set to false.

      style: form

      explode: true

      schema:
@@ -6023,7 +6139,7 @@ components: 
        application/json:

          schema:

            $ref: '#/components/schemas/ProblemDetails'

    ServiceUnavailable:

    GatewayTimeout:

      description: |

        It is used when re-downloading fails.

      headers: