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

As stated by section 6.3.18 Limiting Distributed Operations of the NGSI-LD API... 

As stated by section 6.3.18 Limiting Distributed Operations of the NGSI-LD API v1.8.1 specification, the Registry API operations are always local and thus are not included. This section also add a new clause for including the HTTP Via Header (IETF RFC 7230) for all the operations over the endpoints /entities/, /types/, /attributes/, /subscriptions/, /csourceSubscriptions/, /entityOperations/, /temporal/entities/ and temporal/entityOperations/.
parent 6e3197c1

ngsi-ld-api.yaml

+58 −20
Original line number Diff line number Diff line
@@ -44,6 +44,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      requestBody:

        description: |

          Payload body in the request contains a JSON-LD object which represents the entity that is to be created.
@@ -126,6 +127,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      responses:

        '200':

          description: |
@@ -211,6 +213,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      responses:

        '200':

          description: |
@@ -277,6 +280,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      responses:

        '204':

          description: |
@@ -324,6 +328,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      requestBody:

        description: |

          Entity Fragment containing a complete representation of the Attributes to be merged.
@@ -375,6 +380,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      requestBody:

        description: |

          Entity Fragment containing a complete representation of the Entity to be replaced.
@@ -429,6 +435,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      requestBody:

        description: |

          Entity Fragment containing a complete representation of the Attributes to be added.
@@ -480,6 +487,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      requestBody:

        description: |

          Entity Fragment containing a complete representation of the Attributes to be updated.
@@ -533,6 +541,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      requestBody:

        description: Attribute Fragment containing the elements of the attribute to be updated.

        $ref: '#/components/requestBodies/AttributeFragment'
@@ -573,6 +582,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      responses:

        '204':

          description: |
@@ -607,6 +617,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      requestBody:

        description: Attribute Fragment replacing the previous data.

        $ref: '#/components/requestBodies/AttributeFragment'
@@ -635,8 +646,6 @@ paths: 
        This operation allows registering a context source within an NGSI-LD system.

      operationId: createCSR

      parameters:

        # Local Query param

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

        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'
@@ -726,8 +735,6 @@ paths: 
        - $ref: '#/components/parameters/Query.options.sysAttrs'

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

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

        # Local Query param

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

        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'
@@ -786,8 +793,6 @@ paths: 
        - $ref: '#/components/parameters/Query.options.sysAttrs'

        # Path params

        - $ref: '#/components/parameters/Path.registrationId'

        # Local Query param

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

        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'
@@ -839,8 +844,6 @@ paths: 
      parameters:

        # Path params

        - $ref: '#/components/parameters/Path.registrationId'

        # Local Query param

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

        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'
@@ -886,8 +889,6 @@ paths: 
      parameters:

        # Path params

        - $ref: '#/components/parameters/Path.registrationId'

        # Local Query param

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

        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'
@@ -919,6 +920,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      requestBody:

        description: |

          Payload body in the request contains a JSON-LD object which represents the subscription that is to be created.
@@ -957,6 +959,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      responses:

        '200':

          description: |
@@ -1017,6 +1020,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      responses:

        '200':

          description: |
@@ -1070,6 +1074,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      requestBody:

        description: |

          Subscription Fragment including id, type and any other subscription field to be changed.
@@ -1103,6 +1108,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      responses:

        '204':

          description: |
@@ -1126,11 +1132,10 @@ paths: 
        This operation allows creating a new Context Source Registration Subscription.

      operationId: createCSRSubscription

      parameters:

        # Local Query param

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

        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      requestBody:

        description: |

          Payload body in the request contains a JSON-LD object which represents
@@ -1165,11 +1170,10 @@ paths: 
        - $ref: '#/components/parameters/Query.options.sysAttrs'

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

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

        # Local Query param

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

        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      responses:

        '200':

          description: |
@@ -1225,11 +1229,10 @@ paths: 
        - $ref: '#/components/parameters/Query.options.sysAttrs'

        # Path params

        - $ref: '#/components/parameters/Path.subscriptionId'

        # Local Query param

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

        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      responses:

        '200':

          description: |
@@ -1279,11 +1282,10 @@ paths: 
      parameters:

        # Path params

        - $ref: '#/components/parameters/Path.subscriptionId'

        # Local Query param

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

        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      requestBody:

        description: |

          Subscription Fragment including id, type and any other context
@@ -1313,11 +1315,10 @@ paths: 
      parameters:

        # Path params

        - $ref: '#/components/parameters/Path.subscriptionId'

        # Local Query param

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

        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      responses:

        '204':

          description: |
@@ -1346,6 +1347,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      requestBody:

        description: |

          Array of entities to be created.
@@ -1428,6 +1430,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      requestBody:

        description: |

          Array of entities to be created.
@@ -1517,6 +1520,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      requestBody:

        description: |

          Array of entities to be updated.
@@ -1601,6 +1605,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      requestBody:

        description: |

          Array of String (URIs representing Entity IDs) to be deleted.
@@ -1667,6 +1672,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      requestBody:

        description: Payload body in the request contains a JSON-LD object which represents the query to be performed.

        content:
@@ -1740,6 +1746,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      requestBody:

        description: |

          Array of Entities to be merged.
@@ -1812,6 +1819,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      requestBody:

        description: |

          Payload body in the request contains a JSON-LD object which represents the
@@ -1884,6 +1892,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      responses:

        '200':

          description: |
@@ -1956,6 +1965,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      responses:

        '200':

          description: |
@@ -2008,6 +2018,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      responses:

        '204':

          description: |
@@ -2038,6 +2049,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      requestBody:

        description: |

          EntityTemporal Fragment containing a complete representation of the Attribute instances to be added.
@@ -2077,6 +2089,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      responses:

        '204':

          description: |
@@ -2113,6 +2126,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      requestBody:

        description: EntityTemporal Fragment containing a complete representation of the Attribute instance to be replaced.

        $ref: '#/components/requestBodies/EntityTemporalFragment'
@@ -2151,6 +2165,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      responses:

        '204':

          description: |
@@ -2180,6 +2195,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      requestBody:

        description: Payload body in the request contains a JSON-LD object which represents the query to be performed.

        $ref: '#/components/requestBodies/QueryTemporal'
@@ -2252,6 +2268,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      responses:

        '200':

          description: |
@@ -2320,6 +2337,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      responses:

        '200':

          description: |
@@ -2382,6 +2400,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      responses:

        '200':

          description: |
@@ -2449,6 +2468,7 @@ paths: 
        # Request headers

        - $ref: '#/components/parameters/Headers.Link'

        - $ref: '#/components/parameters/Headers.ngsildTenant'

        - $ref: '#/components/parameters/Headers.via'

      responses:

        '200':

          description: |
@@ -2924,6 +2944,21 @@ components: 
      explode: true

      schema:

        type: string

    Headers.via:

      name: Via

      in: header

      description: |

        6.3.18 Limiting Distributed Operations



        If present, the listing of previously encountered Context Sources supplied is used when determining 

        matching registrations. HTTP Via Header (IETF RFC 7230).



        Any Context Broker implementation passing a distributed operation request onward to another Context Source 

        shall send an additional field value on the Via header field using its own unique Context Source "hostAlias" 

        (see clause 5.2.40) as the pseudonym.

      explode: true

      schema:

        type: string

    Path.attrId:

      name: attrId

      in: path
@@ -3331,6 +3366,9 @@ components: 
      description: |

        6.3.18 Limiting Distributed Operations. If local=true then no Context Source Registrations shall be

        considered as matching to avoid cascading distributed operations (see clause 4.3.6.4).



        The parameter described in this clause limits the execution of an operation to a local Context Source 

        or Context Broker (clause 5.5.13).

      style: form

      explode: true

      schema: