{ "opencollection": "1.0.0", "info": { "name": "ETSI ISG CIM / NGSI-LD API Entry Point Entities API", "version": "latest" }, "items": [ { "info": { "name": "Entities", "type": "folder" }, "items": [ { "info": { "name": "queryEntities", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/entities/", "params": [ { "name": "id", "value": "", "type": "query", "description": "Comma separated list of URIs to be retrieved" }, { "name": "idPattern", "value": "", "type": "query", "description": "Regular expression that must be matched by Entity ids" }, { "name": "type", "value": "", "type": "query", "description": "Comma separated list of Entity type names to be retrieved" }, { "name": "attrs", "value": "", "type": "query", "description": "Comma separated list of attribute names (properties or relationships) to be retrieved" }, { "name": "q", "value": "", "type": "query", "description": "Query" }, { "name": "georel", "value": "", "type": "query", "description": "Geo-relationship" }, { "name": "geometry", "value": "", "type": "query", "description": "Geometry" }, { "name": "coordinates", "value": "", "type": "query", "description": "Coordinates serialized as a string" }, { "name": "geoproperty", "value": "", "type": "query", "description": "The name of the property that contains the geo-spatial data that will be used to resolve the geoquery" }, { "name": "csf", "value": "", "type": "query", "description": "Context Source Filter" }, { "name": "limit", "value": "", "type": "query", "description": "Pagination limit" }, { "name": "options", "value": "", "type": "query", "description": "Options dictionary" } ] }, "docs": "Retrieve a set of entities which matches a specific query from an NGSI-LD system" }, { "info": { "name": "createEntity", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/entities/", "body": { "type": "json", "data": "{}" } }, "docs": "Create a new Entity within an NGSI-LD system" }, { "info": { "name": "retrieveEntityById", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/entities/:entityId", "params": [ { "name": "entityId", "value": "", "type": "path", "description": "Entity Id" }, { "name": "attrs", "value": "", "type": "query", "description": "Comma separated list of attribute names (properties or relationships) to be retrieved" }, { "name": "type", "value": "", "type": "query", "description": "Entity Type" }, { "name": "options", "value": "", "type": "query", "description": "Options dictionary" } ] }, "docs": "Retrieve an specific Entity from an NGSI-LD system. It's possible to specify the Entity attributes to be retrieved by using query parameters" }, { "info": { "name": "removeEntityById", "type": "http" }, "http": { "method": "DELETE", "url": "{{baseUrl}}/entities/:entityId", "params": [ { "name": "entityId", "value": "", "type": "path", "description": "Entity Id" }, { "name": "type", "value": "", "type": "query", "description": "Entity Type" } ] }, "docs": "Removes an specific Entity from an NGSI-LD system" }, { "info": { "name": "appendEntityAttrs", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/entities/:entityId/attrs/", "params": [ { "name": "entityId", "value": "", "type": "path", "description": "Entity Id" }, { "name": "options", "value": "", "type": "query", "description": "Indicates that no attribute overwrite shall be performed" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Append new Entity attributes to an existing Entity within an NGSI-LD system" }, { "info": { "name": "updateEntityAttrs", "type": "http" }, "http": { "method": "PATCH", "url": "{{baseUrl}}/entities/:entityId/attrs/", "params": [ { "name": "entityId", "value": "", "type": "path", "description": "Entity Id" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Update existing Entity attributes within an NGSI-LD system" }, { "info": { "name": "partialAttrUpdate", "type": "http" }, "http": { "method": "PATCH", "url": "{{baseUrl}}/entities/:entityId/attrs/:attrId", "params": [ { "name": "entityId", "value": "", "type": "path", "description": "Entity Id" }, { "name": "attrId", "value": "", "type": "path", "description": "Attribute Id" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Update existing Entity attributes within an NGSI-LD system" }, { "info": { "name": "removeEntityAttr", "type": "http" }, "http": { "method": "DELETE", "url": "{{baseUrl}}/entities/:entityId/attrs/:attrId", "params": [ { "name": "entityId", "value": "", "type": "path", "description": "Entity Id" }, { "name": "attrId", "value": "", "type": "path", "description": "Attribute Id" } ] }, "docs": "Removes an existing Entity attribute within an NGSI-LD system" }, { "info": { "name": "batchEntityCreation", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/entityOperations/create", "body": { "type": "json", "data": "{}" } }, "docs": "Batch Entity creation" }, { "info": { "name": "batchEntityUpdate", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/entityOperations/update", "params": [ { "name": "options", "value": "", "type": "query" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Batch Entity update" }, { "info": { "name": "batchEntityUpsert", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/entityOperations/upsert", "params": [ { "name": "options", "value": "", "type": "query" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Batch Entity upsert" }, { "info": { "name": "batchEntityDelete", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/entityOperations/delete", "body": { "type": "json", "data": "{}" } }, "docs": "Batch Entity delete" }, { "info": { "name": "List Entities", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/v2/entities", "params": [ { "name": "id", "value": "", "type": "query", "description": "A comma-separated list of elements.\nRetrieve entities whose ID matches one of the elements in the list.\nIncompatible with `idPattern`." }, { "name": "type", "value": "", "type": "query", "description": "comma-separated list of elements.\nRetrieve entities whose type matches one of the elements in the list.\nIncompatible with `typePattern`." }, { "name": "idPattern", "value": "", "type": "query", "description": "A correctly formated regular expression.\nRetrieve entities whose ID matches the regular expression. Incompatible with `id`." }, { "name": "typePattern", "value": "", "type": "query", "description": "A correctly formated regular expression.\nRetrieve entities whose type matches the regular expression. Incompatible with `type`." }, { "name": "q", "value": "", "type": "query", "description": "A query expression, composed of a list of statements\nseparated by `;`, i.e., q=statement1;statement2;statement3.\nSee [Simple Query Language specification](#simple_query_language)." }, { "name": "mq", "value": "", "type": "query", "description": "A query expression for attribute metadata,\ncomposed of a list of statements separated by `;`, i.e., mq=statement1;statement2;statement3.\nSee [Simple Query Language specification](#simple_query_language)." }, { "name": "georel", "value": "", "type": "query", "description": "Spatial relationship between matching entities and a\nreference shape. See [Geographical Queries](#geographical_queries)." }, { "name": "geometry", "value": "", "type": "query", "description": "Geografical area to which the query is restricted.\nSee [Geographical Queries](#geographical_queries)." }, { "name": "coords", "value": "", "type": "query", "description": "List of latitude-longitude\npairs of coordinates separated by ';'. See [Geographical Queries](#geographical_queries)." }, { "name": "limit", "value": "", "type": "query", "description": "Limits the number of entities to be retrieved" }, { "name": "offset", "value": "", "type": "query", "description": "Establishes the offset from where entities are retrieved" }, { "name": "attrs", "value": "", "type": "query", "description": "Comma-separated list of attribute names whose data\nare to be included in the response.\nThe attributes are retrieved in the order specified by this parameter. If this parameter is\nnot included, the attributes are retrieved in arbitrary order.\nSee \"Filtering out attributes and metadata\" section for more detail." }, { "name": "metadata", "value": "", "type": "query", "description": "A list of metadata names to include in the response.\nSee \"Filtering out attributes and metadata\" section for more detail." }, { "name": "orderBy", "value": "", "type": "query", "description": "Criteria for ordering results.\nSee \"Ordering Results\" section for details." }, { "name": "options", "value": "", "type": "query", "description": "Options dictionary" } ] }, "docs": "Retrieves a list of entities that match different criteria by id, type, pattern matching (either id or type)\nand/or those which match a query or geographical query (see [Simple Query Language](#simple_query_language) and \n[Geographical Queries](#geographical_queries)). A given entity has to match all the criteria to be retrieved\n(i.e., the criteria is combined in a logical AND way). Note that pattern matching query parameters are incompatible\n(i.e. mutually exclusive) with their corresponding ex" }, { "info": { "name": "Create Entity", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/v2/entities", "headers": [ { "name": "Content-Type", "value": "" } ], "params": [ { "name": "options", "value": "", "type": "query", "description": "Options dictionary" } ] }, "docs": "The payload is an object representing the entity to be created. The object follows\nthe JSON entity representation format (described in a \"JSON Entity Representation\" section).\nResponse:\n* Successful operation uses 201 Created (if upsert option is not used) or 204 No Content (if\n upsert option is used). Response includes a `Location` header with the URL of the\n created entity.\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n more details." }, { "info": { "name": "Retrieve Entity", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/v2/entities/:entityId", "params": [ { "name": "entityId", "value": "", "type": "path", "description": "Id of the entity to be retrieved" }, { "name": "type", "value": "", "type": "query", "description": "Entity type, to avoid ambiguity in case there are several\nentities with the same entity id." }, { "name": "attrs", "value": "", "type": "query", "description": "Comma-separated list of attribute names whose\ndata must be included in the response. The attributes are retrieved in the order specified by\nthis parameter. See \"Filtering out attributes and metadata\" section for more detail.\nIf this parameter is not included, the attributes are retrieved in arbitrary order, and all\nthe attributes of the entity are included in the response." }, { "name": "metadata", "value": "", "type": "query", "description": "A list of metadata names to include in the response.\nSee \"Filtering out attributes and metadata\" section for more detail." }, { "name": "options", "value": "", "type": "query", "description": "Options dictionary" } ] }, "docs": "The response is an object representing the entity identified by the ID. The object follows\nthe JSON entity representation format (described in \"JSON Entity Representation\" section).\nThis operation must return one entity element only, but there may be more than one entity with the\nsame ID (e.g. entities with same ID but different types).\nIn such case, an error message is returned, with the HTTP status code set to 409 Conflict.\nResponse:\n* Successful operation uses 200 OK\n* Errors use a non-2xx an" }, { "info": { "name": "Remove Entity", "type": "http" }, "http": { "method": "DELETE", "url": "{{baseUrl}}/v2/entities/:entityId", "params": [ { "name": "entityId", "value": "", "type": "path", "description": "Id of the entity to be deleted" }, { "name": "type", "value": "", "type": "query", "description": "Entity type, to avoid ambiguity in case there are several\nentities with the same entity id." } ] }, "docs": "Delete the entity.\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." }, { "info": { "name": "Retrieve Entity Attributes", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/v2/entities/:entityId/attrs", "params": [ { "name": "entityId", "value": "", "type": "path", "description": "Id of the entity to be retrieved" }, { "name": "type", "value": "", "type": "query", "description": "Entity type, to avoid ambiguity in case there are several\nentities with the same entity id." }, { "name": "attrs", "value": "", "type": "query", "description": "Comma-separated list of attribute names whose\ndata are to be included in the response. The attributes are retrieved in the order specified\nby this parameter.\nIf this parameter is not included, the attributes are retrieved in arbitrary order, and all\nthe attributes of the entity are included in the response.\nSee \"Filtering out attributes and metadata\" section for more detail." }, { "name": "metadata", "value": "", "type": "query", "description": "A list of metadata names to include in the response.\nSee \"Filtering out attributes and metadata\" section for more detail." }, { "name": "options", "value": "", "type": "query", "description": "Options dictionary" } ] }, "docs": "This request is similar to retreiving the whole entity, however this one omits the `id` and `type`\nfields.\nJust like the general request of getting an entire entity, this operation must return only one\nentity element. If more than one entity with the same ID is found (e.g. entities with\nsame ID but different type), an error message is returned, with the HTTP status code set to\n409 Conflict.\nResponse:\n* Successful operation uses 200 OK\n* Errors use a non-2xx and (optionally) an error payload. See" }, { "info": { "name": "Update or Append Entity Attributes", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/v2/entities/:entityId/attrs", "headers": [ { "name": "Content-Type", "value": "" } ], "params": [ { "name": "entityId", "value": "", "type": "path", "description": "Entity id to be updated" }, { "name": "type", "value": "", "type": "query", "description": "Entity type, to avoid ambiguity in case there are several\nentities with the same entity id." }, { "name": "options", "value": "", "type": "query", "description": "Operations options" } ] }, "docs": "The request payload is an object representing the attributes to append or update. The object follows\nthe JSON entity representation format (described in \"JSON Entity Representation\" section), except\nthat `id` and `type` are not allowed.\nThe entity attributes are updated with the ones in the payload, depending on\nwhether the `append` operation option is used or not.\n* If `append` is not used: the entity attributes are updated (if they previously exist) or appended\n (if they don't previously exis" }, { "info": { "name": "Replace all entity attributes", "type": "http" }, "http": { "method": "PUT", "url": "{{baseUrl}}/v2/entities/:entityId/attrs", "headers": [ { "name": "Content-Type", "value": "" } ], "params": [ { "name": "entityId", "value": "", "type": "path", "description": "Id of the entity in question." }, { "name": "type", "value": "", "type": "query", "description": "Entity type, to avoid ambiguity in case there are several\nentities with the same entity id." }, { "name": "options", "value": "", "type": "query", "description": "Operations options" } ] }, "docs": "The request payload is an object representing the new entity attributes. The object follows\nthe JSON entity representation format (described in a \"JSON Entity Representation\" above), except\nthat `id` and `type` are not allowed.\nThe attributes previously existing in the entity are removed and replaced by the ones in the\nrequest.\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." }, { "info": { "name": "Update Existing Entity Attributes", "type": "http" }, "http": { "method": "PATCH", "url": "{{baseUrl}}/v2/entities/:entityId/attrs", "headers": [ { "name": "Content-Type", "value": "" } ], "params": [ { "name": "entityId", "value": "", "type": "path", "description": "Id of the entity to be updated" }, { "name": "type", "value": "", "type": "query", "description": "Entity type, to avoid ambiguity in case there are several\nentities with the same entity id." }, { "name": "options", "value": "", "type": "query", "description": "Operations options" } ] }, "docs": "The request payload is an object representing the attributes to update. The object follows\nthe JSON entity representation format (described in \"JSON Entity Representation\" section), except\nthat `id` and `type` are not allowed.\nThe entity attributes are updated with the ones in the payload. In addition to that, if one or more\nattributes in the payload doesn't exist in the entity, an error is returned.\nResponse:\n* Successful operation uses 204 No Content\n* Errors use a non-2xx and (optionally) an " } ] } ], "bundled": true }