entities-spec.json

{
	"openapi": "3.0.1",
	"info": {
		"title": "NGSI-LD Entities",
		"version": "latest"
	},
	"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
			  }
			}
		}
	},
	"paths": {
		"/entities/": {
			"get": {
				"description": "Retrieve a set of entities which matches a specific query from an NGSI-LD system",
				"operationId": "queryEntities",
				"parameters": [{
						"$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"
					}
				],
				"responses": {
					"200": {
						"description": "OK",
						"content": {
							"application/json;application/ld+json": {
								"schema": {
									"$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/schema/EntityList.json#"
								},
								"examples": {
									"simple": {
										"externalValue": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/examples/Entity-example.json"
									}
								}
							}
						}
					},
					"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"
								}
							}
						}
					}
				}
			},
			"post": {
				"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/Entity.json#"
				      },
				    }
				  }
				},
				"responses": {
					"201": {
						"description": "Created. Contains the resource URI of the created Entity"
					},
					"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"
								}
							}
						}
					},
					"409": {
						"description": "Already exists",
						"content": {
							"application/json;application/ld+json": {
								"schema": {
									"$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/schema/common.json#/definitions/ProblemDetails"
								}
							}
						}
					},
					"422": {
						"description": "Unprocessable Entity",
						"content": {
							"application/json;application/ld+json": {
								"schema": {
									"$ref": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/schema/common.json#/definitions/ProblemDetails"
								}
							}
						}
					}
				}
			}
		}
	}
}