![\"GitHub\"](\"https://fiware.github.io/tutorials.Getting-Started/icon/GitHub-Mark-32px.png\"){kind=icon}
FIWARE 101: An Introduction to the FIWARE PlatformLet’s start with the data from a supermarket chain’s store finder and create a very simple “Powered by FIWARE” application by passing in the address and location of each store as context data to the FIWARE context broker.
\nThe docker-compose file for this tutorial can be found on GitHub:
FIWARE 101: An Introduction to the FIWARE Platform
Our demo application will only make use of one FIWARE component - the Orion Context Broker . Usage of the Orion Context Broker is sufficient for an application to qualify as “Powered by FIWARE”.
\nCurrently, the Orion Context Broker relies on open source MongoDB technology to keep persistence of the context data it holds. Therefore, the architecture will consist of two elements:
\nSince all interactions between the two elements are initiated by HTTP requests, the entities can be containerized and run from exposed ports.
\n![\"\"](\"https://fiware.github.io/tutorials.Getting-Started/img//architecture.png\")
To keep things simple both components will be run using Docker. Docker is a container technology which allows to different components isolated into their respective environments.
\nFirst pull the necessary Docker images from Docker Hub and create a network for our containers to connect to:
\ndocker pull mongo:3.6\ndocker pull fiware/orion\ndocker network create fiware_default\nA Docker container running a MongoDB database can be started and connected to the network with the following command:
\ndocker run -d --name=context-db --network=fiware_default \\\n --expose=27017 mongo:3.6 --bind_ip_all --smallfiles\nThe Orion Context Broker can be started and connected to the network with the following command:
\ndocker run -d --name orion --network=fiware_default \\\n -p 1026:1026 fiware/orion -dbhost context-db\nYou can check if the Orion Context Broker is running by making an HTTP request to the exposed port:
\ncurl -X GET http://localhost:1026/version\nAlternatively run all your curl commands from within the container network:
\ndocker run --network fiware_default --rm appropriate/curl -s \\\n -X GET http://orion:1026/version\nWhat if I get an error response?
\nIf you get an error response, the Orion Content Broker cannot be found where expected\nfor this tutorial - you will need to substitute the URL and port in each Postman request \nwith the corrected ip address. All the Postman requests in this tutorial assume \nthat orion is available on localhost:1026.
Try the following remedies:
\ndocker ps\nYou should see two containers running. If orion is not running, you can restart the \ncontainers as necessary. This command will also display open port information.
\ndocker-machine and Virtual Box, you will need to retrieve the virtual host ip as shown:curl -X GET http://$(docker-machine ip default):1026/version\nIf you need to update the location of orion:
\n... at the head of the imported postman collectionedit from the dropdownvariables tab and alter the value from localhost:1026 as necessary.As usual, you can check if the Orion Context Broker is running by making an HTTP request to the exposed port.
\nThe format of the version response has not changed for Orion NGSI-LD The release_date must be 16th July 2019 or later to be able to\nwork with the requests defined below.
When creating linked data entities, it is important to use common data models. This will allow us to easily combine data\nfrom multiple sources and remove ambiguity when comparing data coming from different sources.
\nCreating linked data using full qualified names throughout would be painful, as each attribute would need to be a URN,\nso JSON-LD introduces the idea of an @context attribute which can hold pointers to context definitions. To add a\nFIWARE Building data entity,\nthe following @context would be required
{\n \"id\": \"urn:ngsi-ld:Building:store001\",\n \"type\": \"Building\",\n ... other data attributes\n \"@context\": [\n \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld\",\n \"https://schema.lab.fiware.org/ld/fiware-datamodels-context.jsonld\"\n ]\n}\nhttps://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld\nrefers to the Core @context of NSGI-LD, this defines element such as id and type which are common to all NGSI\nentities, as well as defining terms such as Property and Relationship. The core context is so fundamental to\nNGSI-LD, that it is added by default to any @context sent to a request.
https://schema.lab.fiware.org/ld/fiware-datamodels-context.jsonld\nrefers to the definition of standard data models supplied by FIWARE. Adding this to the @context will load the\ndefinitions of all the data models defined by the FIWARE Foundation, a\nsummary of the FQNs related to Building can be seen below:
{\n \"@context\": {\n \"Building\": \"https://uri.fiware.org/ns/datamodels/Building\",\n ... etc\n \"address\": \"http://schema.org/address\",\n \"category\": \"https://uri.fiware.org/ns/datamodels/category\",\n \"location\": \"http://uri.etsi.org/ngsi-ld/location\",\n \"name\": \"http://schema.org/name\",\n ...etc\n }\n}\nIf we include this context definition, it means that we will be able to use short names for Building, address,\nlocation for our entities, but computers will also be able to read the FNQs when comparing with other sources.
To create a valid Building data entity in the context broker, make a POST request to the\nhttp://localhost:1026/ngsi-ld/v1/entities endpoint as shown below. It is essential that the appropriate\nContent-Type: application/ld+json is also used, so that the data entity is recognized as Linked data.
The first request will take some time, as the context broker must navigate and load all of the files mentioned in the\n@context.
Each subsequent entity must have a unique id for the given type
The attributes id and type should be familiar to anyone who has used NSGI v2, and these have not changed. As\nmentioned above, the type should refer to an included data model, in this case Building is being used as a short name\nfor the inclued URN https://uri.fiware.org/ns/datamodels/Building. Thereafter each property is defined as a JSON\nelement containing two attributes, a type and a value.
The type of a property attribute must be one of the following:
\"GeoProperty\": \"http://uri.etsi.org/ngsi-ld/GeoProperty\" for locations. Locations should be specified as\nLongitude-Latitude pairs in GeoJSON format. The preferred name for the\nprimary location attribute is location\"TemporalProperty\": \"http://uri.etsi.org/ngsi-ld/TemporalProperty\" for time-based values. Temporal properties\nshould be Date, Time or DateTime strings encoded be ISO 8601 format - e.g.\nYYYY-MM-DDThh:mm:ssZ\"Property\": \"http://uri.etsi.org/ngsi-ld/Property\" - for everything else\n\nNote: that for simplicity, this data entity has no relationships defined. Relationships must be given the\n
\ntype=\"Relationship. Relationships will be discusssed in a subsequent tutorial.
Properties-of-Properties is the NGSI-LD equivalent of metadata (i.e. \"data about data\"), it is use to describe\nproperties of the attribute value itself like accuracy, provider, or the units to be used. Some built-in metadata\nattributes already exist and these names are reserved:
\ncreatedAt (type: DateTime): attribute creation date as an ISO 8601 string.modifiedAt (type: DateTime): attribute modification date as an ISO 8601 string.Additionally observedAt, datasetId and instanceId may optionally be added in some cases, and location,\nobservationSpace and operationSpace have special meaning for Geoproperties.
In the examples given above, one element of metadata (i.e. a property-of-a-property) can be found within the address\nattribute. a verified flag indicates whether the address has been confirmed. The commonest property-of-a-property is\nunitCode which should be used to hold the UN/CEFACT\nCommon Codes for Units of Measurement.
A consuming application can now request context data by making NGSI-LD HTTP requests to the Orion Context Broker. The\nexisting NGSI-LD interface enables us to make complex queries and filter results and retrieve data with FNQs or with\nshort names.
\nThis example returns the data of all Building entities within the context data The type parameter is mandatory for\nNGSI-LD and is used to filter the response.
The response returns the Core @context by default\n(https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/defaultContext/defaultContext.jsonld) and all attributes are\nexpanded whenever possible.
id, type and location are defined in the core context and are not expanded.address has been mapped to http://schema.org/addressname has been mapped to http://schema.org/namecategory has been mapped to https://uri.fiware.org/ns/datamodels/categoryNote that if an attribute has not been not associated to an FNQ when the entity was created, the short name will\nalways be displayed.
\n","urlObject":{"protocol":"http","path":["v2","entities"],"host":["localhost:1026"],"query":[],"variable":[]}},"response":[],"_postman_id":"0dd59299-1a8a-4830-bb4d-ddcb86e69550"},{"name":"Obtain Entity Data by id","id":"a7c40a56-c5aa-4bb3-b2d0-c54b99461d1f","request":{"method":"GET","header":[],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:1026/v2/entities/urn:ngsi-ld:Store:001?options=keyValues","description":"This example returns the data of urn:ngsi-ld:Store:001.
The response returns the Core @context by default\n(https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/defaultContext/defaultContext.jsonld) and all attributes are\nexpanded whenever possible.
keyValues option in order to get a more compact and brief representation, including just attribute valuesvalues option combined with a list of attribute values attrs for an ordered list of attributes onlyEntity type, to avoid ambiguity in case there are several entities with the same entity id
\n","type":"text/plain"},"key":"type","value":"Store"},{"disabled":true,"description":{"content":"Ordered list of attribute names to display
\n","type":"text/plain"},"key":"attrs","value":"name"}],"variable":[]}},"response":[],"_postman_id":"a7c40a56-c5aa-4bb3-b2d0-c54b99461d1f"},{"name":"Obtain Entity Data by type","id":"186559d1-b3bd-4990-a03a-306728b94765","request":{"method":"GET","header":[],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:1026/v2/entities/?type=Store&options=keyValues","description":"If a reference to the supplied data is supplied, it is possible to return short name data and limit responses to a\nspecific type of data. For example, the request below returns the data of all Building entities within the context\ndata. Use of the type parameter limits the response to Building entities only, use of the options=keyValues query\nparameter reduces the response down to standard JSON-LD.
A Link header must be supplied to associate the short form type=\"Building\"\nwith the FNQ https://uri.fiware.org/ns/datamodels/Building. The full link header syntax can be seen below:
Link: <https://schema.lab.fiware.org/ld/fiware-datamodels-context.jsonld>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\nThe standard HTTP Link header allows metadata (in this case the @context) to be passed in without actually touching\nthe resource in question. In the case of NGSI-LD, the metadata is a file of in application/ld+json format.
Because of the use of the options=keyValues, the response consists of JSON only without the attribute defintions\ntype=\"Property\" or any properties-of-properties elements. You can see that Link header from the request has been\nused as the @context returned in the response.
Entity type, to avoid ambiguity in case there are several entities with the same entity id
\n","type":"text/plain"},"key":"type","value":"Store"},{"description":{"content":"keyValues option in order to get a more compact and brief representation, including just attribute valuesvalues option combined with a list of attribute values attrs for an ordered list of attributes onlyOrdered list of attribute names to display
\n","type":"text/plain"},"key":"attrs","value":"name"}],"variable":[]}},"response":[],"_postman_id":"186559d1-b3bd-4990-a03a-306728b94765"},{"name":"Filter context data by attribute value","id":"fd1485b5-71e6-4da0-bd5b-b234d4bcd8c3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Link","value":"This example returns all Building entiies with the name attribute Checkpoint Markt. Filtering can be done using\nthe q parameter - if a string has spaces in it, it can be URL encoded and held within single quote characters ' =\n%27.
The Link header https://schema.lab.fiware.org/ld/context holds an array of @context as shown:
{\n \"@context\": [\n \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld\",\n \"https://schema.lab.fiware.org/ld/fiware-datamodels-context.jsonld\"\n ]\n}\nand therefore includes the FIWARE Building model.
\nThis means that use of the Link header and the options=keyValues parameter reduces the response to short form\nJSON-LD as shown below:
Entity type, to avoid ambiguity in case there are several entities with the same entity id
\n","type":"text/plain"},"key":"type","value":"Store"},{"description":{"content":"keyValues option in order to get a more compact and brief representation, including just attribute valuesvalues option combined with a list of attribute values attrs for an ordered list of attributes onlyOrdered list of attribute names to display
\n","type":"text/plain"},"key":"attrs","value":"name"}],"variable":[]}},"response":[],"_postman_id":"fd1485b5-71e6-4da0-bd5b-b234d4bcd8c3"},{"name":"Filter context data by comparing the values of an attribute in an Array","id":"83714a3f-566a-46d5-a42c-682925a27f50","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Link","value":"Within the standard Building model, the category attribute refers to an array of strings. This example returns all\nBuilding entities with a category attribute which contains either commercial or office strings. Filtering can be\ndone using the q parameter, comma separating the acceptable values.
The response is returned in JSON-LD format with short form attribute names:
\n","urlObject":{"protocol":"http","path":["v2","entities",""],"host":["localhost:1026"],"query":[{"key":"q","value":"category==%27commercial%27,%27office%27"},{"description":{"content":"Entity type, to avoid ambiguity in case there are several entities with the same entity id
\n","type":"text/plain"},"key":"type","value":"Building"},{"description":{"content":"keyValues option in order to get a more compact and brief representation, including just attribute valuesvalues option combined with a list of attribute values attrs for an ordered list of attributes onlyOrdered list of attribute names to display
\n","type":"text/plain"},"key":"attrs","value":"name"}],"variable":[]}},"response":[],"_postman_id":"83714a3f-566a-46d5-a42c-682925a27f50"},{"name":"Filter context data by sub-attribute value","id":"5a9358e1-f54f-49e1-8115-cf8175552ace","request":{"method":"GET","header":[],"url":"http://localhost:1026/v2/entities/?q=address.addressLocality=='Kreuzberg'&type=Store&options=keyValues","description":"This example returns the data of all Store entities found in the Kreuzberg district of Berlin.
Filtering can be done using the q parameter - sub-attributes are annotated using the dot syntax e.g. address.addressLocality
Because of the use of the options=keyValues, the response consists of JSON only without the attribute type and metadata elements.
Entity type, to avoid ambiguity in case there are several entities with the same entity id
\n","type":"text/plain"},"key":"type","value":"Store"},{"description":{"content":"keyValues option in order to get a more compact and brief representation, including just attribute valuesvalues option combined with a list of attribute values attrs for an ordered list of attributes onlyThis example returns the data of all Store entities with a verified address.
Metadata queries can be made using the mq parameter.
Entity type, to avoid ambiguity in case there are several entities with the same entity id
\n","type":"text/plain"},"key":"type","value":"Store"},{"description":{"content":"keyValues option in order to get a more compact and brief representation, including just attribute valuesvalues option combined with a list of attribute values attrs for an ordered list of attributes onlyThis example returns the data of all Store entities found within 1.5km the Brandenburg Gate in Berlin (52.5162N 13.3777W)
Entity type, to avoid ambiguity in case there are several entities with the same entity id
\n","type":"text/plain"},"key":"type","value":"Store"},{"description":{"content":"keyValues option in order to get a more compact and brief representation, including just attribute valuesvalues option combined with a list of attribute values attrs for an ordered list of attributes onlyOrdered list of attribute names to display
\n","type":"text/plain"},"key":"attrs","value":"name"}],"variable":[]}},"response":[],"_postman_id":"1823197e-92c7-437f-93d7-35d276b79e86"}],"event":[{"listen":"prerequest","script":{"id":"581cc060-de73-4283-915a-fcaa1c126830","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"5215414e-418f-4c32-8070-b68d62c90ea4","type":"text/javascript","exec":[""]}}],"variable":[{"id":"df0c7c83-8325-4d8f-8b3f-bea47630872d","key":"orion","value":"localhost:1026","type":"string"}]}