From f4b91e56309d85393e80b9d29aaa7e6fd23018b0 Mon Sep 17 00:00:00 2001 From: Jose Manuel Cantera Date: Thu, 22 Nov 2018 12:52:37 +0100 Subject: [PATCH] Restoring entities-spec --- spec/updated/entities-spec.json | 302 +++++++++++-------- spec/updated/ngsi-ld-spec-open-api_test.json | 10 +- 2 files changed, 184 insertions(+), 128 deletions(-) diff --git a/spec/updated/entities-spec.json b/spec/updated/entities-spec.json index fb6d38f..6adf2ca 100644 --- a/spec/updated/entities-spec.json +++ b/spec/updated/entities-spec.json @@ -1,83 +1,185 @@ { "openapi": "3.0.1", "info": { - "title": "NGSI-LD Entity Operations", - "version": "0.1" + "title": "NGSI-LD Entities", + "version": "latest" }, - "components": {}, - "paths": { - "/entityOperations/create": { - "post": { - "description": "Batch Entity creation", - "operationId": "batchEntityCreation", - "requestBody": { - "required": true, - "content": { - "application/json;application/ld+json": { - "schema": { - "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/schema/EntityList.json#/definitions/EntityList" - } - } - } - }, - "responses": { - "200": { - "description": "Success", - "content": { - "application/json;application/ld+json": { - "schema": { - "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/schema/BatchOperationResult.json#/definitions/BatchOperationResult" - } - } - } - }, - "400": { - "description": "Bad request", - "content": { - "application/json;application/ld+json": { - "schema": { - "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/schema/common.json#/definitions/ProblemDetails" - } - } - } - } + "components": { + "parameters": { + "id": { + "name": "id", + "description": "Comma separated list of URIs to be retrieved", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "uri" + } + }, + "type": { + "name": "type", + "description": "Comma separated list of Entity type names to be retrieved", + "in": "query", + "required": false, + "schema": { + "type": "string", + "minLength": 1 + } + }, + "idPattern": { + "name": "idPattern", + "description": "Regular expression that must be matched by Entity ids", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "regexp" + } + }, + "attrs": { + "name": "attrs", + "description": "Comma separated list of attribute names (properties or relationships) to be retrieved", + "in": "query", + "required": false, + "schema": { + "type": "string", + "minLength": 1 + } + }, + "q": { + "name": "q", + "description": "Query", + "in": "query", + "required": false, + "schema": { + "type": "string", + "minLength": 1 + } + }, + "georel": { + "name": "georel", + "description": "Geo-relationship", + "in": "query", + "required": false, + "schema": { + "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/schema/common.json#/definitions/georel" + } + }, + "geometry": { + "name": "geometry", + "description": "Geometry", + "in": "query", + "required": false, + "schema": { + "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/schema/common.json#/definitions/geometry" + } + }, + "coordinates": { + "name": "coordinates", + "description": "Coordinates serialized as a string", + "in": "query", + "required": false, + "schema": { + "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/schema/common.json#/definitions/coordinates" + } + }, + "geoproperty": { + "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, + "schema": { + "type": "string", + "minLength": 1 + } + }, + "csf": { + "name": "csf", + "description": "Context Source Filter", + "in": "query", + "required": false, + "schema": { + "type": "string", + "minLength": 1 + } + }, + "limit": { + "name": "limit", + "description": "Pagination limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + }, + "options":{ + "name": "options", + "description": "Options dictionary", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": ["keyValues", "sysAttrs"] } } - }, - "/entityOperations/update": { - "post": { - "description": "Batch Entity update", - "operationId": "batchEntityUpdate", + } + }, + "paths": { + "/entities/": { + "get": { + "description": "Retrieve a set of entities which matches a specific query from an NGSI-LD system", + "operationId": "queryEntities", "parameters": [ { - "name": "options", - "in": "query", - "required": false, - "schema": { - "type": "string", - "enum": [ - "noOverwrite" - ] - } + "$ref": "#/components/parameters/id" + }, + { + "$ref": "#/components/parameters/idPattern" + }, + { + "$ref": "#/components/parameters/type" + }, + { + "$ref": "#/components/parameters/attrs" + }, + { + "$ref": "#/components/parameters/q" + }, + { + "$ref": "#/components/parameters/georel" + }, + { + "$ref": "#/components/parameters/geometry" + }, + { + "$ref": "#/components/parameters/coordinates" + }, + { + "$ref": "#/components/parameters/geoproperty" + }, + { + "$ref": "#/components/parameters/csf" + }, + { + "$ref": "#/components/parameters/limit" + }, + { + "$ref": "#/components/parameters/options" } ], - "requestBody": { - "required": true, - "content": { - "application/json;application/ld+json": { - "schema": { - "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/schema/EntityList.json#/definitions/EntityList" - } - } - } - }, "responses": { "200": { - "description": "Success", + "description": "OK", "content": { "application/json;application/ld+json": { "schema": { - "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/schema/BatchOperationResult.json#/definitions/BatchOperationResult" + "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/schema/EntityList.json#/definitions/EntityList" + }, + "examples": { + "simple": { + "externalValue": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/examples/EntityList-example.json" + } } } } @@ -93,46 +195,23 @@ } } } - } - }, - "/entityOperations/upsert": { + }, "post": { - "description": "Batch Entity upsert", - "operationId": "batchEntityUpsert", - "parameters": [ - { - "name": "options", - "in": "query", - "required": false, - "schema": { - "type": "string", - "enum": [ - "replace", - "update" - ] - } - } - ], + "description": "Create a new Entity within an NGSI-LD system", + "operationId": "createEntity", "requestBody": { "required": true, "content": { "application/json;application/ld+json": { "schema": { - "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/schema/EntityList.json#/definitions/EntityList" + "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/schema/Entity.json#/definitions/Entity" } } } }, "responses": { - "200": { - "description": "Success", - "content": { - "application/json;application/ld+json": { - "schema": { - "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/schema/BatchOperationResult.json#/definitions/BatchOperationResult" - } - } - } + "201": { + "description": "Created. Contains the resource URI of the created Entity" }, "400": { "description": "Bad request", @@ -143,42 +222,19 @@ } } } - } - } - } - }, - "/entityOperations/delete": { - "post": { - "description": "Batch Entity delete", - "operationId": "batchEntityDelete", - "requestBody": { - "required": true, - "content": { - "application/json;application/ld+json": { - "schema": { - "type": "array", - "items": { - "type": "string", - "format": "uri" - }, - "minItems": 1 - } - } - } - }, - "responses": { - "200": { - "description": "Success", + }, + "409": { + "description": "Already exists", "content": { "application/json;application/ld+json": { "schema": { - "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/schema/BatchOperationResult.json#/definitions/BatchOperationResult" + "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/schema/common.json#/definitions/ProblemDetails" } } } }, - "400": { - "description": "Bad request", + "422": { + "description": "Unprocessable Entity", "content": { "application/json;application/ld+json": { "schema": { diff --git a/spec/updated/ngsi-ld-spec-open-api_test.json b/spec/updated/ngsi-ld-spec-open-api_test.json index b5d262e..730c12d 100644 --- a/spec/updated/ngsi-ld-spec-open-api_test.json +++ b/spec/updated/ngsi-ld-spec-open-api_test.json @@ -90,19 +90,19 @@ "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/spec/updated/entity-operations-spec.json#/paths/%2FentityOperations%2Fdelete" }, "/temporal/entities/": { - "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/spec/updated/temporal-entities-spec.json#/paths/%2Ftemporal%2Fentities%2F" + "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/spec/updated/temporal/temporal-entities-spec.json#/paths/%2Ftemporal%2Fentities%2F" }, "/temporal/entities/{entityId}": { - "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/spec/updated/temporal-entity-by-id-spec.json#/paths/%2Ftemporal%2Fentities%2F%7BentityId%7D" + "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/spec/updated/temporal/temporal-entity-by-id-spec.json#/paths/%2Ftemporal%2Fentities%2F%7BentityId%7D" }, "/temporal/entities/{entityId}/attrs/": { - "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/spec/updated/temporal-entity-attrs-spec.json#/paths/%2Ftemporal%2Fentities%2F%7BentityId%7D%2Fattrs%2F" + "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/spec/updated/temporal/temporal-entity-attrs-spec.json#/paths/%2Ftemporal%2Fentities%2F%7BentityId%7D%2Fattrs%2F" }, "/temporal/entities/{entityId}/attrs/{attrId}": { - "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/spec/updated/temporal-entity-attrs-spec.json#/paths/%2Ftemporal%2Fentities%2F%7BentityId%7D%2Fattrs%2F%7BattrId%7D" + "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/spec/updated/temporal/temporal-entity-attrs-spec.json#/paths/%2Ftemporal%2Fentities%2F%7BentityId%7D%2Fattrs%2F%7BattrId%7D" }, "/temporal/entities/{entityId}/attrs/{attrId}/{instanceId}": { - "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/spec/updated/temporal-entity-attrs-spec.json#/paths/%2Ftemporal%2Fentities%2F%7BentityId%7D%2Fattrs%2F%7BattrId%7D%7BinstanceId%7D" + "$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/spec/updated/temporal/temporal-entity-attrs-spec.json#/paths/%2Ftemporal%2Fentities%2F%7BentityId%7D%2Fattrs%2F%7BattrId%7D%7BinstanceId%7D" } } } -- GitLab