Fix description and summary of ALL operations (79271be9) · Commits · CIM - Context Information Management / NGSI-LD API

ngsi-ld-api.yaml

+240 −57

Original line number	Diff line number	Diff line
		@@ -148,7 +148,9 @@ paths:
		summary: \|
		Entity retrieval by id
		description: \|
		5.7.1 Retrieve Entity
		5.7.1 Retrieve Entity.

		This operation allows retrieving an NGSI-LD Entity.
		operationId: retrieveEntity
		parameters:
		# Path params
		@@ -252,9 +254,13 @@ paths:
		- Core API
		- Context Information Provision
		summary: \|
		Entity merge by id
		Entity merge by id.
		description: \|
		5.6.17 Merge Entity
		5.6.17 Merge entity.

		This operation allows modification of an existing NGSI-LD Entity aligning to the JSON Merge Patch
		processing rules defined in IETF RFC 7396 by adding new Attributes (Properties or Relationships)
		or modifying or deleting existing Attributes associated with an existing Entity.
		operationId: mergeEntity
		parameters:
		# Path params
		@@ -298,9 +304,12 @@ paths:
		- Core API
		- Context Information Provision
		summary: \|
		Entity replacement by id
		Entity replacement by id.
		description: \|
		5.6.18 Replace Entity
		5.6.18 Replace entity.

		This operation allows the modification of an existing NGSI-LD Entity
		by replacing all of the Attributes (Properties or Relationships).
		operationId: replaceEntity
		parameters:
		# Path params
		@@ -479,8 +488,13 @@ paths:
		tags:
		- Core API
		- Context Information Provision
		summary: Attribute replace
		description: 5.6.19 Attribute Replace
		summary: \|
		Attribute replace.
		description: \|
		5.6.19 Attribute replace.

		This operation allows the replacement of a single Attribute (Property or Relationship)
		within an NGSI-LD Entity.
		operationId: replaceAttrs
		parameters:
		# Path params
		@@ -513,7 +527,10 @@ paths:
		- Registry API
		- Context Source Registration
		summary: Csource registration creation
		description: 5.9.2 Register Context Source
		description: \|
		5.9.2 Register Context Source.

		This operation allows registering a context source within an NGSI-LD system.
		operationId: createCSR
		parameters:
		# Local Query param
		@@ -549,7 +566,21 @@ paths:
		summary: \|
		Discover Csource registrations
		description: \|
		5.7.2 Query CSRs
		5.10.2 Query Context Source Registrations.

		This operation allows discovering context source registrations from an NGSI-LD system.
		The behaviour of the discovery of context source registrations differs significantly from
		the querying of entities as described in clause 5.7.2. The approach is that the client
		submits a query for entities as described in clause 5.7.2, but instead of receiving
		the Entity information, it receives a list of Context Source Registrations describing
		Context Sources that possibly have some of the requested Entity information. This means
		that the requested Entities and Attributes are matched against the 'information' property
		as described in clause 5.12.

		If no temporal query is present, only Context Source Registrations for Context Sources
		providing latest information, i.e. without specified time intervals, are considered.
		If a temporal query is present only Context Source Registrations with matching time intervals,
		i.e. observationInterval or managementInterval, are considered.
		operationId: queryCSR
		parameters:
		# Query params
		@@ -611,7 +642,10 @@ paths:
		- Registry API
		- Context Source Discovery
		summary: Csource registration retrieval by id
		description: 5.7.1 Retrieve CSR
		description: \|
		5.10.1 Retrieve Context Source Registration.

		This operation allows retrieving a specific context source registration from an NGSI-LD system.
		operationId: retrieveCSR
		parameters:
		# Path params
		@@ -623,7 +657,8 @@ paths:
		- $ref: '#/components/parameters/Headers.ngsildTenant'
		responses:
		200:
		description: A response body containing the JSON-LD representation of the target subscription.
		description: \|
		A response body containing the JSON-LD representation of the target subscription.
		headers:
		NGSILD-Warning:
		$ref: '#/components/headers/NGSILD-Warning'
		@@ -656,7 +691,10 @@ paths:
		- Core API
		- Context Source Registration
		summary: Csource registration update by id
		description: 5.9.3 Update CSR
		description: \|
		5.9.3 Update Context Source Registration.

		This operation allows updating a Context Source Registration in an NGSI-LD system.
		operationId: updateCSR
		parameters:
		# Path params
		@@ -687,7 +725,10 @@ paths:
		- Core API
		- Context Source Registration
		summary: Csource registration deletion by id
		description: 5.9.4 Delete CSR
		description: \|
		5.9.4 Delete Context Source Registration.

		This operation allows deleting a Context Source Registration from an NGSI-LD system.
		operationId: deleteCSR
		parameters:
		# Path params
		@@ -714,7 +755,10 @@ paths:
		- Core API
		- Context Information Subscription
		summary: Create Subscription
		description: 5.8.1 Create Subscription
		description: \|
		5.8.1 Create subscription.

		This operation allows creating a new subscription.
		operationId: createSubscription
		parameters:
		# Local Query param
		@@ -745,7 +789,10 @@ paths:
		- Core API
		- Context Information Consumption
		summary: Retrieve list of Subscriptions
		description: 5.8.4 Query Subscription
		description: \|
		5.8.4 Query Subscriptions.

		This operation allows querying existing Subscriptions.
		operationId: querySubscription
		parameters:
		# Query params
		@@ -759,7 +806,8 @@ paths:
		- $ref: '#/components/parameters/Headers.ngsildTenant'
		responses:
		200:
		description: A response body containing a list of subscriptions.
		description: \|
		A response body containing a list of subscriptions.
		headers:
		NGSILD-Results-Count:
		$ref: '#/components/headers/NGSILD-Results-Count'
		@@ -789,7 +837,10 @@ paths:
		- Core API
		- Context Information Consumption
		summary: Subscription retrieval by id
		description: 5.8.3 Retrieve Subscription
		description: \|
		5.8.3 Retrieve Subscription.

		This operation allows retrieving an existing subscription.
		operationId: retrieveSubscription
		parameters:
		# Path params
		@@ -801,7 +852,8 @@ paths:
		- $ref: '#/components/parameters/Headers.ngsildTenant'
		responses:
		200:
		description: A response body containing the JSON-LD representation of the target subscription.
		description: \|
		A response body containing the JSON-LD representation of the target subscription.
		headers:
		NGSILD-Warning:
		$ref: '#/components/headers/NGSILD-Warning'
		@@ -834,7 +886,10 @@ paths:
		- Core API
		- Context Information Subscription
		summary: Subscription update by id
		description: 5.8.2 Update Subscription
		description: \|
		5.8.2 Update Subscription.

		This operation allows updating an existing subscription.
		operationId: updateSubscription
		parameters:
		# Path params
		@@ -864,7 +919,10 @@ paths:
		- Core API
		- Context Information Subscription
		summary: Subscription deletion by id
		description: 5.8.5 Delete Subscription
		description: \|
		5.8.5 Delete Subscription.

		This operation allows deleting an existing subscription.
		operationId: deleteSubscription
		parameters:
		# Path params
		@@ -891,7 +949,10 @@ paths:
		- Registry API
		- Context Source Registration Subscription
		summary: Create subscription to Csource registration.
		description: 5.11.2 Create CSR Subscription.
		description: \|
		5.11.2 Create Context Source Registration Subscription.

		This operation allows creating a new Context Source Registration Subscription.
		operationId: createCSRSubscription
		parameters:
		# Local Query param
		@@ -927,7 +988,9 @@ paths:
		summary: \|
		Retrieval of list of subscription to Csource registration.
		description: \|
		5.11.5 Query CSR Subscription.
		5.11.5 Query Context Source Registration Subscriptions.

		This operation allows querying existing Context Source Registration Subscriptions.
		operationId: queryCSRSubscription
		parameters:
		# Query params
		@@ -974,7 +1037,10 @@ paths:
		- Registry API
		- Context Source Registration Subscription
		summary: Retrieval of list of subscription to Csource registration.
		description: 5.11.4 Retrieve CSR Subscription.
		description: \|
		5.11.4 Retrieve Context Source Registration Subscription.

		This operation allows retrieving an existing Context Source Registration Subscription.
		operationId: retrieveCSRSubscription
		parameters:
		# Path params
		@@ -1023,7 +1089,10 @@ paths:
		- Registry API
		- Context Source Registration Subscription
		summary: Csource registration subscription update by id.
		description: 5.11.3 Update CSR Subscription.
		description: \|
		5.11.3 Update Context Source Registration Subscription.

		This operation allows updating an existing Context Source Registration Subscription.
		operationId: updateCSRSubscription
		parameters:
		# Path params
		@@ -1054,7 +1123,10 @@ paths:
		- Core API
		- Context Source Registration
		summary: Csource registration subscription deletion by id.
		description: 5.11.6 Delete CSR Subscription.
		description: \|
		5.11.6 Delete Context Source Registration Subscription.

		This operation allows deleting an existing Context Source Registration Subscription.
		operationId: deleteCSRSubscription
		parameters:
		# Path params
		@@ -1149,8 +1221,13 @@ paths:
		tags:
		- Core API
		- Context Information Provision
		summary: Batch Entity create or update (upsert).
		description: 5.6.8 Batch Entity Upsert.
		summary: \|
		Batch Entity create or update (upsert).
		description: \|
		5.6.8 Batch Entity Upsert.

		This operation allows creating a batch of NGSI-LD Entities, updating each of them if they already existed.
		In some database jargon this kind of operation is known as "upsert".
		operationId: upsertBatch
		parameters:
		# Query parameters
		@@ -1217,8 +1294,12 @@ paths:
		tags:
		- Core API
		- Context Information Provision
		summary: Batch Entity update.
		description: 5.6.9 Batch Entity Update.
		summary: \|
		Batch Entity update.
		description: \|
		5.6.9 Batch Entity Update.

		This operation allows updating a batch of NGSI-LD Entities.
		operationId: updateBatch
		parameters:
		# Query parameters
		@@ -1264,8 +1345,12 @@ paths:
		tags:
		- Core API
		- Context Information Provision
		summary: Batch Entity delete.
		description: 5.6.10 Batch Entity Delete.
		summary: \|
		Batch Entity delete.
		description: \|
		5.6.10 Batch Entity Delete.

		This operation allows deleting a batch of NGSI-LD Entities.
		operationId: deleteBatch
		parameters:
		# Local Query param
		@@ -1353,8 +1438,14 @@ paths:
		tags:
		- Core API
		- Context Information Provision
		summary: Batch Entity merge.
		description: 5.6.20 Batch Entity Merge.
		summary: \|
		Batch Entity merge.
		description: \|
		5.6.20 Batch Entity Merge.

		This operation allows modification of a batch of NGSI-LD Entities according to the JSON Merge Patch
		processing rules defined in IETF RFC 7396 by adding new attributes (Properties or Relationships)
		or modifying or deleting existing attributes associated with an existing Entity.
		operationId: mergeBatch
		parameters:
		# Local Query param
		@@ -1398,8 +1489,13 @@ paths:
		tags:
		- Temporal API
		- Temporal Context Information Provision
		summary: Temporal Representation of Entity creation.
		description: 5.6.11 Upsert Temporal Representation
		summary: \|
		Temporal Representation of Entity creation.
		description: \|
		5.6.11 Upsert Temporal Representation.

		This operation allows creating or updating (by adding new Attribute instances)
		a Temporal Representation of an Entity.
		operationId: upsertTemporal
		parameters:
		# Local Query param
		@@ -1504,8 +1600,11 @@ paths:
		tags:
		- Temporal API
		- Temporal Context Information Consumption
		summary: Temporal Representation of Entity retrieval by id.
		description: 5.7.3 Retrieve Temporal Evolution of an Entity.
		summary: Temporal Representation of Entity retrieval by id
		description: \|
		5.7.3 Retrieve Temporal Evolution of an Entity.

		This operation allows retrieving the temporal evolution of an NGSI-LD Entity.
		operationId: retrieveTemporal
		parameters:
		# Path params
		@@ -1560,8 +1659,12 @@ paths:
		tags:
		- Temporal API
		- Temporal Context Information Provision
		summary: Temporal Representation of Entity deletion by id.
		description: 5.6.16 Delete Temporal Representation of an Entity.
		summary: \|
		Temporal Representation of Entity deletion by id.
		description: \|
		5.6.16 Delete Temporal Representation of an Entity.

		This operation allows deleting the Temporal Representation of an Entity.
		operationId: deleteTemporal
		parameters:
		# Path params
		@@ -1587,8 +1690,12 @@ paths:
		tags:
		- Temporal API
		- Temporal Context Information Provision
		summary: 5.6.14 Partial Update Attribute instance in Temporal Representation of an Entity.
		description: 5.6.3 Append Entity Attributes.
		summary: \|
		Temporal Representation of Entity Attribute instance addition
		description: \|
		5.6.12 Append Entity Attributes.

		This operation allows modifying a Temporal Representation of an Entity by adding new Attribute instances.
		operationId: updateAttrsTemporal
		parameters:
		# Path params
		@@ -1654,8 +1761,16 @@ paths:
		tags:
		- Temporal API
		- Temporal Context Information Provision
		summary: Attribute Instance update.
		description: 5.6.14 Partial Update Attribute instance in Temporal Representation of an Entity.
		summary: \|
		Attribute Instance update.
		description: \|
		5.6.14 Partial Update Attribute instance in Temporal Representation of an Entity.

		This operation allows modifying a specific Attribute (Property or Relationship) instance,
		identified by its instanceId, of a Temporal Representation of an Entity.

		This operation enables the correction of wrong information that could have been previously added
		to the Temporal Representation of an Entity.
		operationId: updateAttrsTemporal
		parameters:
		# Path params
		@@ -1685,8 +1800,16 @@ paths:
		tags:
		- Temporal API
		- Temporal Context Information Provision
		summary: Attribute Instance deletion by instance id.
		description: 5.6.15 Delete Attribute Instance from Temporal Representation of an Entity.
		summary: \|
		Attribute Instance deletion by instance id.
		description: \|
		5.6.15 Delete Attribute Instance from Temporal Representation of an Entity.

		This operation allows deleting one Attribute instance (Property or Relationship),
		identified by its instanceId, of a Temporal Representation of an Entity.
		The Attribute itself and all its child elements shall be deleted. This operation enables
		the removal of individual Attribute instances that could have been previously added
		to the Temporal Representation of an Entity.
		operationId: deleteAttrInstanceTemporal
		parameters:
		# Path params
		@@ -1714,8 +1837,12 @@ paths:
		tags:
		- Temporal API
		- Temporal Context Information Consumption
		summary: Temporal Representation of Entity Query based on POST.
		description: 5.7.4 Query Temporal Evolution of Entities.
		summary: Temporal Representation of Entity Query based on POST
		description: \|
		5.7.4 Query Temporal Evolution of Entities.

		This operation allows querying the temporal evolution of Entities present in an NGSI-LD system.
		It is similar to the operation defined by clause 5.7.2 (Query Entities) with the addition of a temporal query.
		operationId: temporalQueryBatch
		parameters:
		# Local Query param
		@@ -1759,7 +1886,11 @@ paths:
		- Core API
		- Context Information Consumption
		summary: Retrieve available entity types
		description: 5.7.5 Retrieve Available Entity Types
		description: \|
		5.7.5 Retrieve Available Entity Types.

		This operation allows retrieving a list of NGSI-LD entity types for which
		entity instances exist within the NGSI-LD system.
		operationId: retrieveTypes
		parameters:
		# Query params
		@@ -1829,8 +1960,16 @@ paths:
		tags:
		- Core API
		- Context Information Consumption
		summary: Retrieve available entity type info
		description: 5.7.7 Retrieve Available Entity Type Information
		summary: Details about available entity type
		description: \|
		5.7.7 Retrieve Available Entity Type information.

		This operation allows retrieving detailed entity type information about a specified NGSI-LD entity
		type for which entity instances exist within the NGSI-LD system. The detailed representation includes
		the type name (as short name if available in the provided @context), the count of available entity
		instances and details about attributes that existing instances of this entity type have, including
		their name (as short name if available in the provided @context) and a list of types the attribute
		can have (e.g. Property, Relationship or GeoProperty).
		operationId: retrieveTypeInfo
		parameters:
		# Path params
		@@ -1872,7 +2011,11 @@ paths:
		- Core API
		- Context Information Consumption
		summary: Retrieve Available Attributes
		description: 5.7.8 Retrieve Available Attributes
		description: \|
		5.7.8 Retrieve Available attributes.

		This operation allows retrieving a list of NGSI-LD attributes that belong to
		entity instances existing within the NGSI- LD system.
		operationId: retrieveAttributes
		parameters:
		# Query params
		@@ -1939,7 +2082,14 @@ paths:
		- Core API
		- Context Information Consumption
		summary: Retrieve Available Attribute Information
		description: 5.7.10 Retrieve Available Attribute Information
		description: \|
		5.7.10 Retrieve Available Attribute information.

		This operation allows retrieving detailed attribute information about a specified NGSI-LD attribute
		that belongs to entity instances existing within the NGSI-LD system. The detailed representation includes
		the attribute name (as short name if available in the provided @context) and the type names
		for which entity instances exist that have the respective attribute, a count of available
		attribute instances and a list of types the attribute can have (e.g. Property, Relationship or GeoProperty).
		operationId: retrieveAttrInfo
		parameters:
		# Path params
		@@ -1979,7 +2129,12 @@ paths:
		post:
		tags:
		- JSON-LD Context API
		description: 5.13.2 Add @context
		summary: Add a user @context to the internal cache
		description: \|
		5.13.2 Add @context.

		With this operation, a client can ask the Broker to store the full content
		of a specific @context, by giving it to the Broker.
		operationId: createContext
		requestBody:
		description: \|
		@@ -2008,7 +2163,20 @@ paths:
		get:
		tags:
		- JSON-LD Context API
		description: 5.13.3 List @contexts
		summary: List all cached @contexts
		description: \|
		5.13.3 List @contexts.

		With this operation a client can obtain a list of URLs that represent all of the @contexts
		stored in the local context store of the Broker. Each URL can be used to download the
		corresponding @context, and, in case the @context's kind is "Cached", it shall be
		the original URL the Broker downloaded the @context from.

		In case a "details" flag is set to true, the client obtains a list of JSON objects,
		each representing information (metadata) about an @context currently stored by the Broker.
		Each JSON object contains information about the @context's original URL (if any), its
		local identifier in the Broker's storage, its kind ("Cached", "Hosted" and "ImplicitlyCreated"),
		its creation timestamp, its expiry date (if "Cached"), and additional optional information.
		operationId: listContexts
		parameters:
		# Query params
		@@ -2059,7 +2227,13 @@ paths:
		get:
		tags:
		- JSON-LD Context API
		description: Serve @context
		summary: Serve one specific user @context
		description: \|
		5.13.4 Serve @context.

		With this operation a client can obtain the full content of a specific @context
		(only for @contexts of kind "Hosted" or "ImplicitlyCreated"), which is currently
		stored in the Broker's internal storage, or its metadata (for all kinds of stored @contexts).
		operationId: retrieveContext
		parameters:
		# Path params
		@@ -2104,7 +2278,16 @@ paths:
		delete:
		tags:
		- JSON-LD Context API
		description: Delete and Reload @context.
		summary: Delete one specific @context from internal cache, possibly re-inserting a freshly downloaded copy of it
		description: \|
		5.13.5 Delete and Reload @context

		With this operation, a client supplies a local identifier to the Broker, indicating
		a stored @context, that the Broker shall remove from its storage. For @contexts of
		kind "Cached" this can also be the original URL the Broker downloaded the @context from.
		If the entry in the local storage that corresponds to the identifier is itself
		an array of @contexts, this operation will not delete the children,
		i.e. the @contexts in the array, but just the entry.
		operationId: deleteContext
		parameters:
		# Path params
		@@ -2173,10 +2356,10 @@ components:
		Implementations should provide descriptive error messages when these situations arise.

		In contrast, GET and DELETE operations always take their input @context from the JSON-LD Link Header.

		explode: true
		schema:
		type: string
		format: uri
		Headers.ngsildCount:
		name: NGSILD-Results-Count
		in: header