diff --git a/NGSI-v2 Linked Data.postman_collection.json b/NGSI-v2 Linked Data.postman_collection.json index f4d8037..cd3d269 100644 --- a/NGSI-v2 Linked Data.postman_collection.json +++ b/NGSI-v2 Linked Data.postman_collection.json @@ -2,7 +2,7 @@ "info": { "_postman_id": "16121a01-e085-4afd-8689-fea63a0d7246", "name": "NGSI-v2 Linked Data", - "description": "This tutorial teaches **NGSI-LD** users about CRUD Operations. The tutorial outlines example usage of the various ways\nof amending context as detailed within the\n[NGSI-LD specification](https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.03.01_60/gs_cim009v010301p.pdf). A\nseries of entities representing temperature sensors are created, modified and deleted based on the temperature sensor\nmodel defined in an [earlier tutorial](https://github.com/FIWARE/tutorials.Understanding-At-Context).\n\nThe `docker-compose` file for this tutorial can be found on GitHub: \n\n![GitHub](https://fiware.github.io/tutorials.NGSI-LD-Operations/icon/GitHub-Mark-32px.png) [FIWARE-LD 103: Manipulating Context Data through CRUD Operations ](https://github.com/FIWARE/tutorials.NGSI-LD-Operations)\n\n# NGSI-LD CRUD Operations\n\n> “Ninety-percent of everything is crud.”\n>\n> ― Theodore Sturgeon, Venture Science Fiction Magazine\n\n**CRUD** Operations (**Create**, **Read**, **Update** and **Delete**) are the four basic functions of persistent\nstorage. For a smart system based on **NGSI-LD**, **CRUD** actions allow the developer to manipulate the context data\nwithin the system. Every **CRUD** operation is clearly defined within the\n[NGSI-LD specification](https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.03.01_60/gs_cim009v010301p.pdf), so all\nNGSI-LD compliant context brokers offer the same interface with the same NGSI-LD operations.\n\nThis tutorial will describe the rational behind each operation, when to use it and how to execute the various **CRUD**\noperations. Since **NGSI-LD** is based on **JSON-LD** passing of `@context` as part of each request in mandatory. For\n**CRUD** operations this is typically passed as a `Link` header, although as we have seen is also possible to pass an\n`@context` attribute as part of the body of the request if `Content-Type: application/ld+json`. However for GET\nrequests, the `@context` cannot be placed in the payload body technique as GET requests have no body.\n\n## Context Entity CRUD Operations\n\nThere are four endpoints used for CRUD operations on an individual data entity. These follow the usual rules for\nhierarchical entities within RESTful applications.\n\nFor operations where the `` is not yet known within the context, or is unspecified, the\n`/ngsi-ld/v1/entities` endpoint is used. As an example, this is used for creating new entities.\n\nOnce an `` is known within the context, individual data entities can be manipulated using the\n`/ngsi-ld/v1/entities/` endpoint.\n\nGeneral Attribute operations on a known entity occur on the `/ngsi-ld/v1/entities//attrs` endpoint and\noperations on individual attributes occur on the `/ngsi-ld/v1/entities//attrs/`.\n\nWhen requesting data or modifying individual entities, the various CRUD operations map naturally to HTTP verbs.\n\n- **GET** - for reading data\n- **POST** - for creating new entities and attributes\n- **PATCH** - for amending entities and attributes\n- **DELETE** - for deleting entities and attributes\n\n## Context Entity Batch Operations\n\nBatch operations allow users to modify multiple data entities with a single request. All batch operations are mapped to\nthe **POST** HTTP verb.\n\n- `/entityOperations/create`\n- `/entityOperations/update`\n- `/entityOperations/upsert`\n- `/entityOperations/delete`\n\n# Prerequisites\n\n## Docker\n\nTo keep things simple all components will be run using [Docker](https://www.docker.com). **Docker** is a container\ntechnology which allows to different components isolated into their respective environments.\n\n- To install Docker on Windows follow the instructions [here](https://docs.docker.com/docker-for-windows/)\n- To install Docker on Mac follow the instructions [here](https://docs.docker.com/docker-for-mac/)\n- To install Docker on Linux follow the instructions [here](https://docs.docker.com/install/)\n\n**Docker Compose** is a tool for defining and running multi-container Docker applications. A\n[YAML file](https://raw.githubusercontent.com/Fiware/tutorials.NGSI-LD-Operations/master/docker-compose/orion-ld.yml) is\nused configure the required services for the application. This means all container services can be brought up in a\nsingle command. Docker Compose is installed by default as part of Docker for Windows and Docker for Mac, however Linux\nusers will need to follow the instructions found [here](https://docs.docker.com/compose/install/)\n\n## Cygwin\n\nWe will start up our services using a simple bash script. Windows users should download [cygwin](http://www.cygwin.com/)\nto provide a command-line functionality similar to a Linux distribution on Windows.\n\n# Architecture\n\nThe demo application will send and receive NGSI-LD calls to a compliant context broker. Since the standardized NGSI-LD\ninterface is available across multiple context brokers, so we only need to pick one - for example the\n[Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/). The application will therefore only make use of\none FIWARE component.\n\nCurrently, the Orion Context Broker relies on open source [MongoDB](https://www.mongodb.com/) technology to keep\npersistence of the context data it holds.\n\nTo promote interoperability of data exchange, NGSI-LD context brokers explicitly expose a\n[JSON-LD `@context` file](https://json-ld.org/spec/latest/json-ld/#the-context) to define the data held within the\ncontext entities. This defines a unique URI for every entity type and every attribute so that other services outside of\nthe NGSI domain are able to pick and choose the names of their data structures. Every `@context` file must be available\non the network. In our case the tutorial application will be used to host a series of static files.\n\nTherefore, the architecture will consist of three elements:\n\n- The [Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/) which will receive requests using\n [NGSI-LD](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/spec/updated/full_api.json)\n- The underlying [MongoDB](https://www.mongodb.com/) database :\n - Used by the Orion Context Broker to hold context data information such as data entities, subscriptions and\n registrations\n- The **Tutorial Application** does the following:\n - Offers static `@context` files defining the context entities within the system.\n\nSince all interactions between the three elements are initiated by HTTP requests, the elements can be containerized and\nrun from exposed ports.\n\n![](https://fiware.github.io/tutorials.NGSI-LD-Operations/img/architecture.png)\n\nThe necessary configuration information can be seen in the services section of the associated `orion-ld.yml` file:\n\n```yaml\norion:\n image: fiware/orion-ld\n hostname: orion\n container_name: fiware-orion\n depends_on:\n - mongo-db\n networks:\n - default\n ports:\n - \"1026:1026\"\n command: -dbhost mongo-db -logLevel DEBUG\n healthcheck:\n test: curl --fail -s http://orion:1026/version || exit 1\n```\n\n```yaml\nmongo-db:\n image: mongo:3.6\n hostname: mongo-db\n container_name: db-mongo\n expose:\n - \"27017\"\n ports:\n - \"27017:27017\"\n networks:\n - default\n command: --nojournal\n```\n\n```yaml\ntutorial:\n image: fiware/tutorials.ngsi-ld\n hostname: tutorial\n container_name: fiware-tutorial\n networks:\n default:\n aliases:\n - context\n expose:\n - 3000\n```\n\nThe necessary configuration information can be seen in the services section of the associated `docker-compose.yml` file.\nIt has been described in a [previous tutorial](https://github.com/FIWARE/tutorials.Working-with-At-Context/)\n\n# Start Up\n\nAll services can be initialised from the command-line by running the\n[services](https://github.com/FIWARE/tutorials.NGSI-LD-Operations/blob/master/services) Bash script provided within the\nrepository. Please clone the repository and create the necessary images by running the commands as shown:\n\n```bash\ngit clone https://github.com/FIWARE/tutorials.NGSI-LD-Operations.git\ncd tutorials.NGSI-LD-Operations\n\n./services orion|scorpio\n```\n\n> **Note:** If you want to clean up and start over again you can do so with the following command:\n>\n> ```\n> ./services stop\n> ```", + "description": "This tutorial teaches **NGSI-LD** users about CRUD Operations. The tutorial outlines example usage of the various ways\nof amending context as detailed within the\n[NGSI-LD specification](https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.03.01_60/gs_cim009v010301p.pdf). A\nseries of entities representing temperature sensors are created, modified and deleted based on the temperature sensor\nmodel defined in an [earlier tutorial](https://github.com/FIWARE/tutorials.Understanding-At-Context).\n\nThe `docker-compose` file for this tutorial can be found on GitHub: \n\n![GitHub](https://fiware.github.io/tutorials.NGSI-LD-Operations/icon/GitHub-Mark-32px.png) [FIWARE-LD 103: Manipulating Context Data through CRUD Operations ](https://github.com/FIWARE/tutorials.NGSI-LD-Operations)\n\n# NGSI-LD CRUD Operations\n\n> “Ninety-percent of everything is crud.”\n>\n> ― Theodore Sturgeon, Venture Science Fiction Magazine\n\n**CRUD** Operations (**Create**, **Read**, **Update** and **Delete**) are the four basic functions of persistent\nstorage. For a smart system based on **NGSI-LD**, **CRUD** actions allow the developer to manipulate the context data\nwithin the system. Every **CRUD** operation is clearly defined within the\n[NGSI-LD specification](https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.03.01_60/gs_cim009v010301p.pdf), so all\nNGSI-LD compliant context brokers offer the same interface with the same NGSI-LD operations.\n\nThis tutorial will describe the rational behind each operation, when to use it and how to execute the various **CRUD**\noperations. Since **NGSI-LD** is based on **JSON-LD** passing of `@context` as part of each request in mandatory. For\n**CRUD** operations this is typically passed as a `Link` header, although as we have seen is also possible to pass an\n`@context` attribute as part of the body of the request if `Content-Type: application/ld+json`. However for GET\nrequests, the `@context` cannot be placed in the payload body technique as GET requests have no body.\n\n## Context Entity CRUD Operations\n\nThere are four endpoints used for CRUD operations on an individual data entity. These follow the usual rules for\nhierarchical entities within RESTful applications.\n\nFor operations where the `` is not yet known within the context, or is unspecified, the\n`/ngsi-ld/v1/entities` endpoint is used. As an example, this is used for creating new entities.\n\nOnce an `` is known within the context, individual data entities can be manipulated using the\n`/ngsi-ld/v1/entities/` endpoint.\n\nGeneral Attribute operations on a known entity occur on the `/ngsi-ld/v1/entities//attrs` endpoint and\noperations on individual attributes occur on the `/ngsi-ld/v1/entities//attrs/`.\n\nWhen requesting data or modifying individual entities, the various CRUD operations map naturally to HTTP verbs.\n\n- **GET** - for reading data\n- **POST** - for creating new entities and attributes\n- **PATCH** - for amending entities and attributes\n- **DELETE** - for deleting entities and attributes\n\n## Context Entity Batch Operations\n\nBatch operations allow users to modify multiple data entities with a single request. All batch operations are mapped to\nthe **POST** HTTP verb.\n\n- `/entityOperations/create`\n- `/entityOperations/update`\n- `/entityOperations/upsert`\n- `/entityOperations/delete`\n\n# Prerequisites\n\n## Docker\n\nTo keep things simple all components will be run using [Docker](https://www.docker.com). **Docker** is a container\ntechnology which allows to different components isolated into their respective environments.\n\n- To install Docker on Windows follow the instructions [here](https://docs.docker.com/docker-for-windows/)\n- To install Docker on Mac follow the instructions [here](https://docs.docker.com/docker-for-mac/)\n- To install Docker on Linux follow the instructions [here](https://docs.docker.com/install/)\n\n**Docker Compose** is a tool for defining and running multi-container Docker applications. A\n[YAML file](https://raw.githubusercontent.com/Fiware/tutorials.NGSI-LD-Operations/master/docker-compose/orion-ld.yml) is\nused configure the required services for the application. This means all container services can be brought up in a\nsingle command. Docker Compose is installed by default as part of Docker for Windows and Docker for Mac, however Linux\nusers will need to follow the instructions found [here](https://docs.docker.com/compose/install/)\n\n## WSL\n\nWe will start up our services using a simple bash script. Windows users should download the [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install)\nto provide a command-line functionality similar to a Linux distribution on Windows.\n\n# Architecture\n\nThe demo application will send and receive NGSI-LD calls to a compliant context broker. Since the standardized NGSI-LD\ninterface is available across multiple context brokers, so we only need to pick one - for example the\n[Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/). The application will therefore only make use of\none FIWARE component.\n\nCurrently, the Orion Context Broker relies on open source [MongoDB](https://www.mongodb.com/) technology to keep\npersistence of the context data it holds.\n\nTo promote interoperability of data exchange, NGSI-LD context brokers explicitly expose a\n[JSON-LD `@context` file](https://json-ld.org/spec/latest/json-ld/#the-context) to define the data held within the\ncontext entities. This defines a unique URI for every entity type and every attribute so that other services outside of\nthe NGSI domain are able to pick and choose the names of their data structures. Every `@context` file must be available\non the network. In our case the tutorial application will be used to host a series of static files.\n\nTherefore, the architecture will consist of three elements:\n\n- The [Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/) which will receive requests using\n [NGSI-LD](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/spec/updated/full_api.json)\n- The underlying [MongoDB](https://www.mongodb.com/) database :\n - Used by the Orion Context Broker to hold context data information such as data entities, subscriptions and\n registrations\n- The **Tutorial Application** does the following:\n - Offers static `@context` files defining the context entities within the system.\n\nSince all interactions between the three elements are initiated by HTTP requests, the elements can be containerized and\nrun from exposed ports.\n\n![](https://fiware.github.io/tutorials.NGSI-LD-Operations/img/architecture.png)\n\nThe necessary configuration information can be seen in the services section of the associated `orion-ld.yml` file:\n\n```yaml\norion:\n image: fiware/orion-ld\n hostname: orion\n container_name: fiware-orion\n depends_on:\n - mongo-db\n networks:\n - default\n ports:\n - \"1026:1026\"\n command: -dbhost mongo-db -logLevel DEBUG\n healthcheck:\n test: curl --fail -s http://orion:1026/version || exit 1\n```\n\n```yaml\nmongo-db:\n image: mongo:3.6\n hostname: mongo-db\n container_name: db-mongo\n expose:\n - \"27017\"\n ports:\n - \"27017:27017\"\n networks:\n - default\n command: --nojournal\n```\n\n```yaml\ntutorial:\n image: fiware/tutorials.ngsi-ld\n hostname: tutorial\n container_name: fiware-tutorial\n networks:\n default:\n aliases:\n - context\n expose:\n - 3000\n```\n\nThe necessary configuration information can be seen in the services section of the associated `docker-compose.yml` file.\nIt has been described in a [previous tutorial](https://github.com/FIWARE/tutorials.Working-with-At-Context/)\n\n# Start Up\n\nAll services can be initialised from the command-line by running the\n[services](https://github.com/FIWARE/tutorials.NGSI-LD-Operations/blob/master/services) Bash script provided within the\nrepository. Please clone the repository and create the necessary images by running the commands as shown:\n\n```bash\ngit clone https://github.com/FIWARE/tutorials.NGSI-LD-Operations.git\ncd tutorials.NGSI-LD-Operations\n\n./services orion|scorpio\n```\n\n> **Note:** If you want to clean up and start over again you can do so with the following command:\n>\n> ```\n> ./services stop\n> ```", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "_exporter_id": "513743", "_collection_link": "https://fiware.postman.co/workspace/NGSI-LD-tutorials~60157bf9-a93f-4c6e-90d1-0917133c1872/collection/513743-16121a01-e085-4afd-8689-fea63a0d7246?action=share&source=collection_link&creator=513743"