{ "swagger": "2.0", "info": { "description": "This swagger 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": "0.0.11", "title": "ETSI ISG CIM / NGSI-LD API", "termsOfService": "http://tbd.tbd/tbd/", "contact": { "email": "NGSI-LD@etsi.org" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" } }, "externalDocs": { "description": "Find out more about the ETSI ISG Context Information Management", "url": "https://portal.etsi.org/tb.aspx?tbid=854&SubTB=854" }, "host": "tbd.tbd.tbd", "basePath": "/v1", "tags": [ { "name": "ETSI", "description": "European Telecommunications Standards Institute", "externalDocs": { "description": "Find out more", "url": "http://www.etsi.org" } },{ "name": "CIM", "description": "Context Information Management", "externalDocs": { "description": "Find out more", "url": "https://portal.etsi.org/tb.aspx?tbid=854&SubTB=854" } },{ "name": "OMA", "description": "Open Mobile Alliance", "externalDocs": { "description": "Find out more", "url": "http://openmobilealliance.org" } },{ "name": "NSGI", "description": "Next Generation Service Interfaces", "externalDocs": { "description": "Find out more", "url": "http://www.openmobilealliance.org/release/NGSI/V1_0-20120529-A/OMA-AD-NGSI-V1_0-20120529-A.pdf" } },{ "name": "FIWARE NSGI v2", "description": "FIWARE Next Generation Service Interfaces v2", "externalDocs": { "description": "Find out more", "url": "https://orioncontextbroker.docs.apiary.io/#" } },{ "name": "JSON-LD", "description": "JSON for Linking Data", "externalDocs": { "description": "Find out more", "url": "https://json-ld.org/" } },{ "name": "NGSI-LD API", "description": "API defined by the ETSI ISG CIM", "externalDocs": { "description": "Find out more", "url": "http://www.etsi.org/deliver/etsi_gs/CIM/001_099/004/01.01.01_60/gs_CIM004v010101p.pdf" } } ], "schemes": [ "http", "https" ], "paths": { "/entities/": { "get": { "description": "Retrieve a set of entities which matches a specific query from an NGSI-LD system", "operationId": "queryEntities", "parameters": [ { "name": "id", "description": "Comma separated list of URIs to be retrieved", "in": "query", "required": false, "type": "string" },{ "name": "type", "description": "Comma separated list of Entity type names to be retrieved", "in": "query", "required": false, "type": "string" },{ "name": "idPattern", "description": "Regular expression that must be matched by Entity ids", "in": "query", "required": false, "type": "string" },{ "name": "attrs", "description": "Comma separated list of attribute names (properties or relationships) to be retrieved", "in": "query", "required": false, "type": "string" },{ "name": "q", "description": "Query", "in": "query", "required": false, "type": "string" },{ "name": "georel", "description": "Geo-relationship", "in": "query", "required": false, "type": "string" },{ "name": "geometry", "description": "Geometry", "in": "query", "required": false, "type": "string" },{ "name": "coordinates", "description": "Coordinates serialized as a string", "in": "query", "required": false, "type": "string" },{ "name": "geoproperty", "description": "The name of the property that contains the geo-spatial data that will be used to resolve the geoquery", "in": "query", "required": false, "type": "string" } ], "produces": [ "application/json", "application/ld+json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "ngsild_entity_schema.json#/definitions/EntityList" } }, "400": { "description": "Bad request", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } } } }, "post": { "description": "Create a new Entity within an NGSI-LD system", "operationId": "createEntity", "parameters": [ { "name": "EntityDescription", "description": "Payload body in the request contains a JSON-LD object which represents the Entity that is to be created", "in": "body", "required": true, "schema": { "$ref": "ngsild_entity_schema.json#/definitions/EntityDescription" } } ], "consumes": [ "application/json", "application/ld+json" ], "responses": { "201": { "description": "Created. Contains the resource URI of the created Entity", "schema": { "type": "string" } }, "400": { "description": "Bad request", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } }, "409": { "description": "Already exists", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } }, "422": { "description": "Unprocessable Entity", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } } } } }, "/entities/{entityId}": { "get": { "description": "Retrieve an specific Entity from an NGSI-LD system. It's possible to specify the Entity attributes to be retrieved by using query parameters", "operationId": "retrieveEntityById", "parameters": [ { "name": "entityId", "description": "Id (URI) of the Entity to be retrieved", "in": "path", "required": true, "type": "string" },{ "name": "attrs", "description": "Comma separated list of attribute names (properties or relationships) to be included in the response", "in": "query", "required": false, "type": "string" } ], "produces": [ "application/json", "application/ld+json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "ngsild_entity_schema.json#/definitions/Entity" } }, "400": { "description": "Bad Request", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } } } }, "delete": { "description": "Removes an specific Entity from an NGSI-LD system", "operationId": "removeEntityById", "parameters": [ { "name": "entityId", "description": "Id (URI) of the Entity to be removed", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "No Content. The entity was removed successfully" }, "400": { "description": "Bad Request", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } } } } }, "/entities/{entityId}/attrs/": { "post": { "description": "Append new Entity attributes to an existing Entity within an NGSI-LD system", "operationId": "appendEntityAttrs", "parameters": [ { "name": "entityId", "description": "Id (URI) of the Entity where to append new attributes", "in": "path", "required": true, "type": "string" }, { "name": "noOverwrite", "description": "Indicates that no attribute overwrite shall be performed", "in": "query", "required": false, "type": "string" }, { "name": "EntityFragment", "description": "Entity Fragment containing a complete representation of the attributes to be added", "in": "body", "required": true, "schema": { "$ref": "ngsild_entity_schema.json#/definitions/EntityFragment" } } ], "consumes": [ "application/json", "application/ld+json" ], "responses": { "204": { "description": "No Content. All the attributes were appended successfully" }, "207": { "description": "Multi-Status. Only the attributes included in the response payload were successfully appended", "schema": { "$ref": "ngsild_entity_schema.json#/definitions/EntityAttrList" } }, "400": { "description": "Bad Request", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } } } }, "patch": { "description": "Update existing Entity attributes within an NGSI-LD system", "operationId": "updateEntityAttrs", "parameters": [ { "name": "entityId", "description": "Id (URI) of the Entity where to update the specified attributes", "in": "path", "required": true, "type": "string" }, { "name": "EntityFragment", "description": "Entity Fragment containing a complete representation of the attributes to be updated", "in": "body", "required": true, "schema": { "$ref": "ngsild_entity_schema.json#/definitions/EntityFragment" } } ], "consumes": [ "application/json", "application/ld+json" ], "responses": { "204": { "description": "No Content. All the attributes were appended successfully" }, "207": { "description": "Multi-Status. Only the attributes included in the response payload were successfully appended", "schema": { "$ref": "ngsild_entity_schema.json#/definitions/EntityAttrList" } }, "400": { "description": "Bad Request", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } } } } }, "/entities/{entityId}/attrs/{attrId}": { "patch": { "description": "Update existing Entity attributes within an NGSI-LD system", "operationId": "partialAttrUpdate", "parameters": [ { "name": "entityId", "description": "Id (URI) of the Entity where to update the specified attribute", "in": "path", "required": true, "type": "string" }, { "name": "attrId", "description": "Attribute name (property or relationship) to be updated", "in": "path", "required": true, "type": "string" }, { "name": "EntityFragment", "description": "Entity Fragment containing the elements of the attribute to be updated", "in": "body", "required": true, "schema": { "$ref": "ngsild_entity_schema.json#/definitions/EntityFragment" } } ], "consumes": [ "application/json", "application/ld+json" ], "responses": { "204": { "description": "No Content. The attribute was updated successfully" }, "400": { "description": "Bad Request", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } } } }, "delete": { "description": "Removes an existing Entity attribute within an NGSI-LD system", "operationId": "removeEntityAttr", "parameters": [ { "name": "entityId", "description": "Id (URI) of the Entity where to remove the specified attribute", "in": "path", "required": true, "type": "string" }, { "name": "attrId", "description": "Attribute name (property or relationship) to be removed", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "No Content. The attribute was removed successfully" }, "400": { "description": "Bad Request", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } } } } }, "/csourceRegistrations/": { "post": { "description": "Registers a new context source within an NGSI-LD system", "operationId": "registerCsource", "parameters": [ { "name": "CsourceRegistrationDescription", "description": "Payload body in the request contains a JSON-LD object which represents the context source registration that is to be created", "in": "body", "required": true, "schema": { "$ref": "ngsild_csource_schema.json#/definitions/CsourceRegistrationDescription" } } ], "consumes": [ "application/json", "application/ld+json" ], "responses": { "201": { "description": "Created. Contains the resource URI of the created context source registration resource", "schema": { "type": "string" } }, "400": { "description": "Bad request", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } }, "409": { "description": "Already exists", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } }, "422": { "description": "Unprocessable Context Source Registration", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } } } }, "get": { "description": "Retrieve a set of context sources which matches a specific query from an NGSI-LD system", "operationId": "queryCsources", "parameters": [ { "name": "id", "description": "Comma separated list of URIs to be retrieved", "in": "query", "required": false, "type": "string" },{ "name": "type", "description": "Comma separated list of context sources type names to be retrieved", "in": "query", "required": false, "type": "string" },{ "name": "idPattern", "description": "Regular expression that must be matched by context source ids", "in": "query", "required": false, "type": "string" },{ "name": "attrs", "description": "Comma separated list of attribute names (properties or relationships) to be retrieved", "in": "query", "required": false, "type": "string" },{ "name": "q", "description": "Query", "in": "query", "required": false, "type": "string" },{ "name": "georel", "description": "Geo-relationship", "in": "query", "required": false, "type": "string" },{ "name": "geometry", "description": "Geometry", "in": "query", "required": false, "type": "string" },{ "name": "coordinates", "description": "Coordinates serialized as a string", "in": "query", "required": false, "type": "string" },{ "name": "geoproperty", "description": "The name of the property that contains the geo-spatial data that will be used to resolve the geo-query", "in": "query", "required": false, "type": "string" } ], "produces": [ "application/json", "application/ld+json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "ngsild_csource_schema.json#/definitions/CsourceRegistrationList" } }, "400": { "description": "Bad request", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } } } } }, "/csourceRegistrations/{registrationId}": { "get": { "description": "Retrieves a specific context source registration from an NGSI-LD system", "operationId": "retrieveCsource", "parameters": [ { "name": "registrationId", "description": "Id (URI) of the context source registration to be retrieved", "in": "path", "required": true, "type": "string" } ], "produces": [ "application/json", "application/ld+json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "ngsild_csource_schema.json#/definitions/CsourceRegistration" } }, "400": { "description": "Bad Request", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } } } }, "delete": { "description": "Removes an specific context source registration within an NGSI-LD system", "operationId": "removeCsource", "parameters": [ { "name": "registrationId", "description": "Id (URI) of the context source registration to be removed", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "No Content. The context source registration was removed successfully" }, "400": { "description": "Bad Request", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } } } }, "patch": { "description": "Updates a specific context source registration within an NGSI-LD system", "operationId": "updateCsource", "parameters": [ { "name": "registrationId", "description": "Id (URI) of the context source registration to be updated", "in": "path", "required": true, "type": "string" }, { "name": "CsourceRegistrationFragment", "description": "Payload body in the request contains a JSON-LD object which represents the context source registration that is to be updated", "in": "body", "required": true, "schema": { "$ref": "ngsild_csource_schema.json#/definitions/CsourceRegistrationFragment" } } ], "consumes": [ "application/json", "application/ld+json" ], "responses": { "204": { "description": "No Content. The context source registration was successfully updated" }, "400": { "description": "Bad Request", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } } } } }, "/subscriptions/": { "post": { "description": "Creates a new Subscription within an NGSI-LD system", "operationId": "createSubscription", "parameters": [ { "name": "SubscriptionDescription", "description": "Payload body in the request contains a JSON-LD object which represents the Subscription that is to be created", "in": "body", "required": true, "schema": { "$ref": "ngsild_subscriptions_schema.json#/definitions/SubscriptionDescription" } } ], "consumes": [ "application/json", "application/ld+json" ], "responses": { "201": { "description": "Created. Contains the resource URI of the created Entity resource", "schema": { "type": "string" } }, "400": { "description": "Bad Request", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } }, "409": { "description": "Already exists", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } } } }, "get": { "description": "Retrieves the subscriptions available in an NGSI-LD system", "operationId": "retrieveSubscriptions", "parameters": [ { "name": "limit", "description": "Maximum number of subscriptions to be retrieved", "in": "query", "required": false, "type": "string" } ], "produces": [ "application/json", "application/ld+json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "ngsild_subscriptions_schema.json#/definitions/SubscriptionList" } }, "400": { "description": "Bad Request", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } } } } }, "/subscriptions/{subscriptionId}": { "get": { "description": "Retrieves a specific Subscription from an NGSI-LD system", "operationId": "retrieveSubscription", "parameters": [ { "name": "subscriptionId", "description": "Id (URI) of the Subscription to be retrieved", "in": "path", "required": true, "type": "string" } ], "produces": [ "application/json", "application/ld+json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "ngsild_subscriptions_schema.json#/definitions/Subscription" } }, "400": { "description": "Bad Request", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } } } }, "delete": { "description": "Removes a specific Subscription from an NGSI-LD system", "operationId": "removeSubscription", "parameters": [ { "name": "subscriptionId", "description": "Id (URI) of the Subscription to be removed", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "No Content. The Subscription was removed successfully" }, "400": { "description": "Bad Request", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } } } }, "patch": { "description": "Updates a specific Subscription within an NGSI-LD system", "operationId": "updateSubscription", "parameters": [ { "name": "subscriptionId", "description": "Id (URI) of the Subscription to be updated", "in": "path", "required": true, "type": "string" }, { "name": "SubscriptionFragment", "description": "Subscription Fragment including id, type and any other Subscription field to be updated", "in": "body", "required": true, "schema": { "$ref": "ngsild_subscriptions_schema.json#/definitions/SubscriptionFragment" } } ], "consumes": [ "application/json", "application/ld+json" ], "responses": { "204": { "description": "No Content. The Subscription was updated successfully" }, "400": { "description": "Bad Request", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } } } } }, "/csourceSubscriptions/": { "post": { "description": "Creates a context source discovery Subscription within an NGSI-LD system", "operationId": "createCSourceSubscription", "parameters": [ { "name": "SubscriptionDescription", "description": "Payload body in the request contains a JSON-LD object which represents the context source discovery Subscription that is to be created", "in": "body", "required": true, "schema": { "$ref": "ngsild_subscriptions_schema.json#/definitions/SubscriptionDescription" } } ], "consumes": [ "application/json", "application/ld+json" ], "responses": { "201": { "description": "Created. Contains the resource URI of the created context source discovery Subscription resource", "schema": { "type": "string" } }, "400": { "description": "Bad Request", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } }, "409": { "description": "Already exists", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } } } }, "get": { "description": "Retrieves the context source discovery subscriptions available in an NGSI-LD system", "operationId": "retrieveCSourceSubscriptions", "parameters": [ { "name": "limit", "description": "Maximum number of subscriptions to be retrieved", "in": "query", "required": false, "type": "string" } ], "produces": [ "application/json", "application/ld+json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "ngsild_subscriptions_schema.json#/definitions/SubscriptionList" } }, "400": { "description": "Bad Request", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } } } } }, "/csourceSubscriptions/{subscriptionId}": { "get": { "description": "Retrieves a specific context source discovery Subscription from an NGSI-LD system", "operationId": "retrieveCSourceSubscription", "parameters": [ { "name": "subscriptionId", "description": "Id (URI) context source discovery Subscription to be retrieved", "in": "path", "required": true, "type": "string" } ], "produces": [ "application/json", "application/ld+json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "ngsild_subscriptions_schema.json#/definitions/Subscription" } }, "400": { "description": "Bad Request", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } } } }, "delete": { "description": "Removes a specific context source discovery Subscription from an NGSI-LD system", "operationId": "removeCSourceSubscription", "parameters": [ { "name": "subscriptionId", "description": "Id (URI) context source discovery Subscription to be removed", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "No Content. The context source discovery Subscription was removed successfully" }, "400": { "description": "Bad Request", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } } } }, "patch": { "description": "Updates a specific context source discovery Subscription within an NGSI-LD system", "operationId": "updateCSourceSubscription", "parameters": [ { "name": "subscriptionId", "description": "Id (URI) context source discovery Subscription to be updated", "in": "path", "required": true, "type": "string" }, { "name": "SubscriptionFragment", "description": "Subscription Fragment including id, type and any other Subscription field to be updated", "in": "body", "required": true, "schema": { "$ref": "ngsild_subscriptions_schema.json#/definitions/SubscriptionFragment" } } ], "consumes": [ "application/json", "application/ld+json" ], "responses": { "204": { "description": "No Content. The context source discovery Subscription was updated successfully" }, "400": { "description": "Bad Request", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "ngsild_schema.json#/definitions/ApiErrorResponse" } } } } } } }