Introducing Essentials, an API designed to simplify Thing In operations, focusing on user experience and core functionalities in order to manage digital twins.
¶ Getting started
This section contains all the prerequisites you should know before you start using Essentials API.
¶ Authentication
Essentials authentication is the same as Thingin API : Bearer Authentication.
You will need to generate an authentication token via the /auth route by passing a username and a password (Basic authentication), which will then need to be passed in the headers of your future requests. Don't forget to select the desired output format (default is application/json, plain/text is also available)
You can also find it in the Thing In user interface. (develop menu > Get my Thing in token)
¶ Input & output format
The number of formats that Essentials can process has been reduced to standardize the different routes. Therefore, two output formats were chosen: application/json and application/json-seq * ; and only one input format: application/json.
* json-seq is only used in list operations. It allows streamed responses.
¶ Success & errors codes
Success and error codes have also been generalized for all http calls.
Success codes:
Create : 201 Created
Read : 200 OK
Update : 204 NoContent
Delete: 204 NoContent
Error codes:
CRUD : 400 Bad Request (BadFormatException)
RUD: 404 NotFound (NotFoundException)
C: 409 Conflit (AlreadyExistsException)
CRUD: 500 InternalServerError (BackendException)
CRUD: 503 Service Unavailable
¶ Identifiers (IDs)
With Essentials, it is possible to use either the UUID or the name of the resource (for example: name for label, IRI for an avatar, etc.) to perform queries on a specific element. This should make your use easier because the old API only offered to use the UUID stored in the database.
¶ Pagination
In order to use pagination from streamed responses, you will need to use two differents query parameters in your query: offset & limit. These two are integers.
Offset indicates the starting point from which to retrieve results, meanwhile limit specifies the number of items to retrieve from the offset position.
By default, offset is equal to 0 and limit is equal to 100.
WARNING: for twin nodes, you can't specify an offset if you don't specify any limit.
For example: you can search from the 100th to 1000th twin node but you can't search from the 100th until the end.
¶ Twin spaces (previously domains)
Twin spaces are containers of twin nodes. Twin nodes should belong to a single twin space.
Twin spaces can be built in a hierarchical way, i.e. hierarchical levels in the IRIs of twin spaces and twin nodes. In that case, it is possible to search on twin spaces and sub-twin spaces in a single query, using the parent/general twin space as the filter.
You can read the previous section for a better understanding of twin spaces (previously domains) definition.
| Method | HTTP request | Description |
|---|---|---|
| twinSpaceCreate | POST /essentials/twinSpaces | Create a single twin space |
| twinSpaceDelete | DELETE /essentials/twinSpaces/ID | Delete an twin space knowing its ID (uuid or iri) |
| twinSpaceGet | GET /essentials/twinSpaces/ID | Get an twin space knowing its ID (uuid or iri) |
| twinSpacesList | GET /essentials/list/twinSpaces | List twin spaces |
| twinSpacesStream | GET /essentials/twinSpaces | List twin spaces in a continuous stream |
¶ twinSpacesCreate ( POST /essentials/twinSpaces )
Create a single twin space.
Payload :
| Name | Type | Description | Notes |
|---|---|---|---|
| iri | String | IRI of the twin space | mandatory |
| expireAfter | Date | date the domain expires | optional |
| historized | Boolean | if true, domain is historized | optional |
| multiRelationship | Boolean | if true, domain allows multi relationship between twin nodes | optional |
{
"iri": "http://www.example.com/my-favorite-historized-twin-space",
"historized": true,
"multiRelationship": true,
"expireAfter": 9007199254740991
}
Return type :
| Name | Type | Description |
|---|---|---|
| uuid | UUID | UUID of the created twin space |
¶ twinSpacesDelete ( DELETE /essentials/twinSpaces/{id} )
Delete an twin space knowing its ID (uuid or iri).
Parameters :
| Name | Type | Description | Notes |
|---|---|---|---|
| id | String | UUID or IRI of the twin space | mandatory in path |
¶ twinSpacesGet ( GET /essentials/twinSpaces/{id} )
Get an twin space knowing its ID (uuid or iri).
Parameters :
| Name | Type | Description | Notes |
|---|---|---|---|
| id | String | UUID or IRI of the twin space | mandatory in path |
Return type :
| Name | Type | Description | Notes |
|---|---|---|---|
| iri | String | ||
| uuid | UUID | ||
| owner | String | optional | |
| expireAfter | Long | optional | |
| creationDate | Date | ||
| historized | Boolean | optional | |
| multiRelationship | Boolean | optional |
{
"iri": "string",
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"owner": "string",
"expireAfter": 9007199254740991,
"creationDate": "2024-04-03T12:20:20.639Z",
"historized": true,
"multiRelationship": true
}
¶ twinSpacesList ( GET /essentials/list/twinSpaces )
List twin spaces.
Query parameters :
| Name | Type | Description | Notes |
|---|---|---|---|
| owner | String | optional | |
| historized | Boolean | optional | |
| expirable | Boolean | optional | |
| iriPrefix | String | optional | |
| multiRelationship | Boolean | optional | |
| sort | enum: CreationDate, CreationDateDesc, Iri, IriDesc | optional | |
| offset | Integer | Indicates the starting point from which to retrieve results | optional |
| limit | Integer | Specifies the number of results to retrieve from the offset position, with a maximum set to 1000 | optional |
Return type :
List of twin spaces (see GET /essentials/twinSpaces/{id})
¶ twinSpacesStream (GET /essentials/twinSpaces )
List twin spaces in a continuous stream
Query parameters :
| Name | Type | Description | Notes |
|---|---|---|---|
| owner | String | optional | |
| historized | Boolean | optional | |
| expirable | Boolean | optional | |
| iriPrefix | String | optional | |
| multiRelationship | Boolean | optional | |
| sort | enum: CreationDate, CreationDateDesc, Iri, IriDesc | optional | |
| offset | Integer | Indicates the starting point from which to retrieve results | optional |
| limit | Integer | Specifies the number of results to retrieve from the offset position, with a maximum set to 1000 | optional |
Return type :
Stream (json-seq) of twin spaces (see GET /essentials/twinSpaces/{id})
¶ Twin nodes (previously avatars)
Thing'in platform stores twin nodes which are digital representations of physical things.
A twin node can represent a connected device (as customarily used in the IoT), a non-connected thing, or a system made up of such things in the environments such as trees, streets, etc….
Thing'in is built upon a graph database, where twin nodes are the nodes of the graph.
A twin node belongs to a single twin space. To ease the identification of the twin node (IRI), the IRI is built with the twin space name and an identifier suffix string. The identifier string can not contain a / character.
Example :
twin space iri = http://www.orange-labs.com/thingin/
twin node iri = http://www.orange-labs.com/thingin/livebox
twin node2 iri = http://www.orange-labs.com/thingin/livebox2
As the twin node IRI is unique, there is only one avatar with a given id within a twin space.
You can check previous docs with "avatar" words for a better understanding.
| Method | HTTP request | Description |
|---|---|---|
| twinNodesCreate | POST /essentials/twinNodes | Create a twin node |
| twinNodesDataPropertyDelete | DELETE /essentials/twinNodes/ID/properties/ | Remove an twin node data property |
| twinNodesDataPropertyGet | GET /essentials/twinNodes/ID/properties/ | Get a twin node property |
| twinNodesDataPropertyUpsert | POST /essentials/twinNodes/ID/properties | Add or update a twin node property |
| twinNodesDelete | DELETE /essentials/twinNodes/ID | Delete a twin node knowing its ID (uuid or iri) |
| twinNodesGet | GET /essentials/twinNodes/ID | Get a twin node knowing its ID (uuid or iri) |
| twinNodesList | GET /essentials/list/twinNodes | List twin nodes |
| twinNodesStream | GET /essentials/twinNodes | List twin nodes in a continuous stream |
| twinNodesUpdate | PUT /essentials/twinNodes/ID | Update a twin node |
¶ twinNodesCreate ( POST /essentials/twinNodes )
Create a twin node.
Payload :
| Name | Type | Description | Notes |
|---|---|---|---|
| iri | String | The unique twin node user-oriented identifier | mandatory |
| types | List<String> | The twin node semantic classes and/or labels | mandatory |
| visibility | enum: Undefined, All, Tipod, Owner | visibility of the twin node | mandatory |
| properties | Map<String, any> | properties attached to the twin node | mandatory |
{
"iri": "string",
"types": [
"string"
],
"visibility": "All",
"properties": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}
Return type :
| Name | Type | Description |
|---|---|---|
| uuid | UUID | UUID of the created twin node |
{
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
¶ twinNodesDataPropertyDelete ( DELETE /essentials/twinNodes/{id}/properties/{name} )
Remove an twin node data property.
Parameters :
| Name | Type | Description | Notes |
|---|---|---|---|
| id | String | UUID or IRI of the twin node | mandatory in path |
| name | String | name of the property to be removed | mandatory in path |
¶ twinNodesDataPropertyGet ( GET /essentials/twinNodes/{id}/properties/{name} )
Get a twin node property.
Parameters :
| Name | Type | Description | Notes |
|---|---|---|---|
| id | String | UUID or IRI of the twin node | mandatory in path |
| name | String | name of the property to be get | mandatory in path |
Return type :
| Name | Type | Description |
|---|---|---|
| value | any | value of the property |
| name | String | name of the property |
{
"name": "string",
"value": "string"
}
¶ twinNodesDataPropertyUpsert ( POST /essentials/twinNodes/{id}/properties )
Add or update a twin node property
Payload :
| Name | Type | Description |
|---|---|---|
| value | any | value of the property |
| name | String | name of the property |
{
"name": "string",
"value": "string"
}
¶ twinNodesDelete ( DELETE /essentials/twinNodes/{id} )
Delete a twin node knowing its ID (uuid or iri).
Parameters :
| Name | Type | Description | Notes |
|---|---|---|---|
| id | String | UUID or IRI of the twin node | mandatory in path |
¶ twinNodesGet ( GET /essentials/twinNodes/{id} )
Get a twin node knowing its ID (uuid or iri).
Parameters :
| Name | Type | Description | Notes |
|---|---|---|---|
| id | String | UUID or IRI of the twin node | mandatory in path |
Return type :
Twin node
| Name | Type | Description | Notes |
|---|---|---|---|
| uuid | UUID | Twin node unique identifier | |
| iri | String | The unique twin node user-oriented identifier | |
| twinsSpace | String | The domain to which this twin node belongs to | |
| types | List<String> | The twin node semantic classes and/or labels | |
| ontologyInstance | Boolean | true if the twin node is an individual in an ontology - false if it is a user defined twin node | |
| visibility | enum: Undefined, All, Tipod, Owner | visibility of the twin node | |
| owner | String | The source identifier from which this twin node have been created | |
| creationDate | Date | Creation date of the twin node | |
| lastUpdated | Date | Last update date | optional |
| outgoingRelationships | List<TwinNodeOutgoingRelationship> | Outgoing edges of this twin node, if requested, if not remains empty | optional |
| properties | Map<String, any> | properties attached to the twin node |
where TwinNodeOutgoingRelationship for outgoingRelationships is
| Name | Type | Description |
|---|---|---|
| uuid | String | The edge unique identifier |
| type | String | Either the object property name or a defined property type label |
| targetIRI | String | Twin node IRI at the origin of this relation |
| targetUUID | UUID | Twin node UUID at the target of this relation |
| properties | Map<String, any> | properties attached to the outgoing relationship |
json example for a twin node:
{
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"iri": "string",
"twinsSpace": "string",
"types": [
"string"
],
"ontologyInstance": true,
"visibility": "All",
"owner": "string",
"creationDate": "2024-04-03T11:52:30.234Z",
"lastUpdated": "2024-04-03T11:52:30.234Z",
"outgoingRelationships": [
{
"uuid": "string",
"type": "string",
"targetIRI": "string",
"targetUUID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"properties": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}
],
"properties": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}
¶ twinNodesList ( GET /essentials/list/twinNodes )
List twin nodes.
Query parameters :
| Name | Type | Description | Notes |
|---|---|---|---|
| twinsSpace | String | ||
| iri | String | ||
| types | List<String> | ||
| withOutgoingRelationship | Boolean | optional | |
| ownerUUID | String | ||
| offset | Integer | Indicates the starting point from which to retrieve results | optional |
| limit | Integer | Specifies the number of results to retrieve from the offset position, with a maximum set to 1000 | optional |
Return type :
List of twin nodes (see GET /essentials/twinnodes/{id}).
¶ twinNodesStream ( GET /essentials/twinNodes )
List twin nodes in a continuous stream.
Query parameters :
| Name | Type | Description | Notes |
|---|---|---|---|
| twinsSpace | String | ||
| iri | String | ||
| types | List<String> | ||
| withOutgoingRelationship | Boolean | optional | |
| ownerUUID | String | ||
| offset | Integer | Indicates the starting point from which to retrieve results | optional |
| limit | Integer | Specifies the number of results to retrieve from the offset position, with a maximum set to 1000 | optional |
Return type :
Stream (json-seq) of twin nodes (see GET /essentials/twinNodes/{id})
¶ twinNodesUpdate ( PUT /essentials/twinNodes/{id} )
Update a twin node.
Payload :
| Name | Type | Description | Notes |
|---|---|---|---|
| types | List | The twin node semantic classes and/or labels | mandatory |
| visibility | enum: Undefined, All, Tipod, Owner | mandatory | |
| properties | Map<String, any> | mandatory |
{
"types": [
"string"
],
"visibility": "All",
"properties": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}
¶ Relationships (previously edges or relationships)
A relationship is identified with it origin twin node, its target twin node and its type (non multirelationship twins space), or for multirelationship twins spaces with these informations plus a ref property
| Method | HTTP request | Description |
|---|---|---|
| relationshipsCreate | POST /essentials/relationships | Create a single relationship |
| relationshipsDelete | DELETE /essentials/relationships/ID | Delete an relationship knowing its UUID |
| relationshipsGet | GET /essentials/relationships/ID | Get an relationship knowing its UUID |
| relationshipsList | GET /essentials/list/relationships | List relationships |
| relationshipsPropertiesDelete | DELETE /essentials/relationships/ID/properties/ | Remove an relationship property |
| relationshipsPropertiesGet | GET /essentials/relationships/ID/properties/ | Get an relationship data property |
| relationshipsPropertiesUpsert | POST /essentials/relationships/ID/properties | Add or update an relationship property |
| relationshipsStream | GET /essentials/relationships | List relationships in a continuous stream |
| relationshipsUpdate | PUT /essentials/relationships/ID | Update an relationship |
| relationshipsUpsert | PUT /essentials/relationships | Create or update an relationship |
¶ relationshipsCreate ( POST /essentials/relationships )
Create a single relationship. If the relationship already exist and the twins space is not a multirelationship one, a conflict error is returned
Payload :
| Name | Type | Description | Notes |
|---|---|---|---|
| type | String | type of the relationship | mandatory |
| originIRI | String | IRI of the origin twin node | mandatory |
| targetIRI | String | IRI of the target twin node | mandatory |
| properties | Map<String, any> | properties attached to the relationship | mandatory |
{
"type": "string",
"originIRI": "string",
"targetIRI": "string",
"properties": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}
Return type :
| Name | Type | Notes |
|---|---|---|
| relationship | Relationship | see [GET /essentials/relationships/{id}] |
{
"relationship": {
"uuid": "string",
"type": "string",
"originIRI": "string",
"targetIRI": "string"
}
}
¶ relationshipsDelete ( DELETE /essentials/relationships/{id} )
Delete an relationship knowing its UUID.
Parameters :
| Name | Type | Description | Notes |
|---|---|---|---|
| id | String | UUID of the relationship | mandatory in path |
¶ relationshipsGet ( GET /essentials/relationships/{id} )
Get an relationship knowing its UUID.
Parameters :
| Name | Type | Description | Notes |
|---|---|---|---|
| id | String | UUID of the relationship. | mandatory in path |
Return type :
Relationship:
| Name | Type | Description |
|---|---|---|
| uuid | String | The edge unique identifier |
| type | String | Either the object property name or a defined property type label |
| originIRI | String | Twin node UUID at the origin of this relation |
| originUUID | UUID | Twin node IRI at the origin of this relation |
| targetIRI | String | Twin node UUID at the target of this relation |
| targetUUID | UUID | Twin node IRI at the target of this relation |
| properties | Map<String, any> | properties attached to the relationship |
{
"uuid": "string",
"type": "string",
"originIRI": "string",
"originUUID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"targetIRI": "string",
"targetUUID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"properties": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}
¶ relationshipsList ( GET /essentials/list/relationships )
List relationships.
Query parameters :
| Name | Type | Description | Notes |
|---|---|---|---|
| originIRI | String | optional | |
| originUUID | UUID | optional | |
| targetIRI | String | optional | |
| targetUUID | UUID | optional | |
| type | String | optional | |
| offset | Integer | Indicates the starting point from which to retrieve results | optional |
| limit | Integer | Specifies the number of results to retrieve from the offset position | optional |
Return type :
List of relationship (see GET /essentials/relationships/{id})
¶ relationshipsPropertiesDelete ( DELETE /essentials/relationships/{id}/properties/{name} )
Remove a relationship property.
Parameters :
| Name | Type | Description | Notes |
|---|---|---|---|
| id | String | UUID of the relationship | mandatory in path |
| name | String | name of the property | mandatory in path |
¶ relationshipsPropertiesGet ( GET /essentials/relationships/{id}/properties/{name} )
Get an relationship data property.
Parameters :
| Name | Type | Description | Notes |
|---|---|---|---|
| id | String | UUID of the relationship | mandatory in path |
| name | String | name of the property | mandatory in path |
Return type :
| Name | Type | Description |
|---|---|---|
| value | any | value of the property |
| name | String | name of the property |
{
"name": "string",
"value": "string"
}
¶ relationshipsPropertiesUpsert ( POST /essentials/relationships/{id}/properties )
Add or update an relationship property.
Payload :
| Name | Type | Description |
|---|---|---|
| value | any | value of the property |
| name | String | name of the property |
{
"name": "string",
"value": "string"
}
¶ relationshipsStream ( GET /essentials/relationships )
List relationships in a continuous stream.
Query parameters :
| Name | Type | Description | Notes |
|---|---|---|---|
| originIRI | String | optional | |
| originUUID | UUID | optional | |
| targetIRI | String | optional | |
| targetUUID | UUID | optional | |
| type | String | optional | |
| offset | Integer | Indicates the starting point from which to retrieve results | optional |
| limit | Integer | Specifies the number of results to retrieve from the offset position | optional |
Return type :
Stream (json-seq) of relationship (see GET /essentials/relationships/{id})
¶ relationshipsUpdate ( PUT /essentials/relationships/{id} )
Update an relationship with their UUID.
Payload :
| Name | Type |
|---|---|
| properties | Map<String, any> |
{
"properties": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}
¶ relationshipsUpsert ( PUT /essentials/relationships )
Create or update an relationship. If a relationship already exists with the same origin, target and type (for non relationships twins spaces) and additionally with the same ref (for multireltionships twins space), the propertes are updated
Payload :
| Name | Type | Description | Notes |
|---|---|---|---|
| type | String | type of the relationship | mandatory |
| originIRI | String | IRI of the origin twin node | mandatory |
| targetIRI | String | IRI of the target twin node | mandatory |
| properties | Map<String, any> | properties attached to the relationship | mandatory |
{
"type": "string",
"originIRI": "string",
"targetIRI": "string",
"properties": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}
Return type :
| Name | Type | Notes |
|---|---|---|
| relationship | Relationship | see GET /essentials/relationships/ |
{
"relationship": {
"uuid": "string",
"type": "string",
"originIRI": "string",
"targetIRI": "string"
}
}
¶ Labels
Read this section to understand what labels are made for.
| Method | HTTP request | Description |
|---|---|---|
| labelCreate | POST /essentials/labels | Create a single label |
| labelDelete | DELETE /essentials/labels/ID | Delete an label knowing its ID (uuid or iri) |
| labelGet | GET /essentials/labels/ID | Get an label knowing its ID (uuid or name) |
| labelList | GET /essentials/list/labels | List labels |
| labelStream | GET /essentials/labels | List labels in a continuous stream |
| labelUpdate | PUT /essentials/labels/ID | Update a label |
¶ labelCreate ( POST /essentials/labels )
Create a single label.
Payload :
| Name | Type | Notes |
|---|---|---|
| name | String | mandatory |
| description | String | mandatory |
| type | enum: Instance, Property, Relationship | mandatory |
{
"name": "string",
"description": "string",
"type": "string"
}
Return type :
| Name | Type |
|---|---|
| uuid | UUID |
| name | String |
{
"uuid": "string",
"name": "string"
}
¶ labelDelete ( DELETE /essentials/labels/{id} )
Delete an label knowing its ID (UUID or IRI).
Parameters :
| Name | Type | Description | Notes |
|---|---|---|---|
| id | String | UUID or IRI of the label | mandatory in path |
¶ labelGet ( GET /essentials/labels/{id} )
Get an label knowing its ID (uuid or name)
Parameters :
| Name | Type | Description | Notes |
|---|---|---|---|
| id | String | UUID or name of the label | mandatory in path |
Return type :
| Name | Type |
|---|---|
| uuid | UUID |
| name | String |
| description | String |
| category | enum: Instance, Property, Relationship |
{
"uuid": "string",
"name": "string",
"description": "string",
"category": "string"
}
¶ labelList ( GET /essentials/list/labels )
List labels.
Query parameters :
| Name | Type | Description | Notes |
|---|---|---|---|
| namePrefix | String | a prefix of the labels to find. | optional |
| keywords | List<String> | keywords separated with coma to find into the description. | optional |
| description | String | optional | |
| type | enum: Instance, Property, Relationship | optional | |
| offset | Integer | Indicates the starting point from which to retrieve results | optional |
| limit | Integer | Specifies the number of results to retrieve from the offset position, with a maximum set to 1000 | optional |
Return type :
List of label (see GET /essentials/labels/{id})
[
{
"uuid": "string",
"name": "string",
"description": "string",
"category": "string"
},
{
"uuid": "string",
"name": "string",
"description": "string",
"category": "string"
}
]
¶ labelStream ( GET /essentials/labels )
List labels in a continuous stream.
Query parameters :
| Name | Type | Description | Notes |
|---|---|---|---|
| namePrefix | String | a prefix of the labels to find. | optional |
| keywords | List<String> | keywords separated with coma to find into the description. | optional |
| description | String | optional | |
| type | enum: Instance, Property, Relationship | optional | |
| offset | Integer | Indicates the starting point from which to retrieve results | optional |
| limit | Integer | Specifies the number of results to retrieve from the offset position, with a maximum set to 1000 | optional |
Return type :
Stream (json-seq) of label (see GET /essentials/labels/{id})
¶ labelUpdate ( PUT /essentials/labels/{id} )
Update a label
Payload :
| Name | Type |
|---|---|
| description | String |
{
"description": "string"
}
¶ Tools
With the Tools API, you can get:
- twin nodes UUID with their IRI
- twin spaces UUID with their IRI
- relationships UUID with their originIRI, targetIRI, and type
- labels UUDI with their name
in order to make the switch easier with UUID. Try it out !
¶ Search
In the essentials API, all requests from querying the graph, historized or not, are gathered in the same endpoint, with the stream and the list variant.
¶ searchStream ( POST /essentials/search )
Make a query on the graph
Payload :
5 types of differents query types are available:
¶ SearchForHistoryMatches
| Name | Type | Notes |
|---|---|---|
| @kind | Enum | value: SearchForHistoryMatches |
| query | String | mandatory. Temporal cypher query |
| matchingMode | enum: MatchingModeAtEnd, MatchingModeAtStart, MatchingModeIsIn | default: MatchingModeIsIn. data to be returned for each state change timestamp : is-in (everything), at-start/at-end (only what has been modified) |
| withStartIntervalsTimestamps | Boolean | default: true. get the initial state for each timerange start timestamp |
| withResultsValidityTimeranges | Boolean | default: true. To get for each twin node, relationship, data property its validity timerange |
| offset | Integer | optional: indicates the starting point from which to retrieve results |
| limit | Integer | optional: Specifies the number of results to retrieve from the offset position, with a maximum set to 1000 |
For the content of the query, see Historization
Example
{
"query": "RANGE_SLICE [2022-12-15T17:01:47.6Z; 2025-12-15T22:00:00.883748836Z) MATCH (n) WHERE n.domain = 'http://stephanie/test/historized/' RETURN n",
"@kind":"SearchForHistoryMatches"
}
Return type :
| Name | Type |
|---|---|
| matches | Array of MatchingGraphEntity |
| stateTimestamp | date-time |
Example
{
"matches": [
{
"@kind": "MatchingGraphEntity",
"entity": {
"@kind": "GraphTwinNode",
"uuid": "d5aa18c6-35c8-5028-b0bf-4e3f06a055d5",
"iri": "http://stephanie/test/historized/test1",
"twinSpace": "http://stephanie/test/historized/",
"types": [
"http://www.w3.org/2002/07/owl#Thing"
],
"typesTimeRange": {
"start": "2024-05-30T07:09:19.190Z",
"end": "2024-05-30T07:10:57.722Z"
},
"properties": {},
"timeRange": {
"start": "2024-05-30T07:09:19.190Z"
}
},
"variableName": "n"
}
],
"stateTimestamp": "2024-05-30T07:09:19.190Z"
}
¶ SearchForMatches
| Name | Type | Notes |
|---|---|---|
| @kind | Enum | value: SearchForMatches |
| query | String | mandatory. Graph query using the standard cypher query language |
| offset | Integer | optional: indicates the starting point from which to retrieve results |
| limit | Integer | optional: Specifies the number of results to retrieve from the offset position, with a maximum set to 1000 |
For the content of the query, see CypherForThinginQuery
Example
{
"query": "MATCH (n) WHERE n.domain = 'http://stephanie/test/historized/' RETURN n",
"@kind":"SearchForMatches"
}
Return type :
| Name | Type |
|---|---|
| matches | Array of MatchingGraphEntity |
| stateTimestamp | date-time |
Example
{
"matches": [
{
"@kind": "MatchingGraphEntity",
"entity": {
"@kind": "GraphTwinNode",
"uuid": "d5aa18c6-35c8-5028-b0bf-4e3f06a055d5",
"iri": "http://stephanie/test/historized/test1",
"twinSpace": "http://stephanie/test/historized/",
"types": [
"http://www.w3.org/2002/07/owl#Thing"
],
"typesTimeRange": {
"start": "2024-05-30T07:09:19.190Z",
"end": "2024-05-30T07:10:57.722Z"
},
"properties": {},
"timeRange": {
"start": "2024-05-30T07:09:19.190Z"
}
},
"variableName": "n"
}
],
"stateTimestamp": "2024-05-30T07:09:19.190Z"
}
¶ SearchUsingTIQL
| Name | Type | Notes |
|---|---|---|
| @kind | Enum | value: SearchUsingTIQL |
| query | Json | mandatory. Graph query using the ThingIn query language |
| withRelationship | Boolean | optional. default:true |
| offset | Integer | optional: indicates the starting point from which to retrieve results |
| limit | Integer | optional: Specifies the number of results to retrieve from the offset position, with a maximum set to 1000 |
For the content of the query, see Avatars_search
Example
{
"query": {"$domain":"http://net-twins/HUAWEI_LANNION/"},
"@kind":"SearchUsingTIQL"
}
Return type :
| Name | Type |
|---|---|
| matches | Array of MatchingGraphEntity |
| stateTimestamp | date-time |
Example
{
"matches": [
{
"@kind": "MatchingGraphEntity",
"entity": {
"@kind": "GraphTwinNode",
"uuid": "011d3fb0-8df8-5d88-9195-0840ef1afcee",
"iri": "http://net-twins/HUAWEI_LANNION/HUAWEI_LANNION__link__167772650_TNG3WSS060901-0-1-23-DM2_167773147_TMB1CMD402-0-5-20-RC__oms-element__167772650_TNG3DAFS02-0-3",
"twinSpace": "http://net-twins/HUAWEI_LANNION/",
"types": [
"http://orange.thingin.ietf/ietf-network1#Amplifier"
],
"properties": {
"http://orange.thingin.ietf/ietf-network1#in-voa": {
"value": 0
},
"cG9z": {
"value": {
"coordinates": [
-2.419225,
48.1947
],
"type": "Point"
}
},
"http://orange.thingin.ietf/ietf-network1#total-output-power": {
"value": 7
},
"http://orange.thingin.ietf/ietf-network1#oms-element-uid": {
"value": "167772650/TNG3DAFS02-0-3"
},
"http://orange.thingin.ietf/ietf-network1#actual-gain": {
"value": 23.1
},
"http://www.opengis.net/gml/pos": {
"value": "{\"coordinates\": [-2.419225, 48.1947], \"type\": \"Point\"}"
},
"http://orange.thingin.ietf/ietf-network1#name": {
"value": "TNG3DAFS02::C"
},
"http://orange.thingin.ietf/ietf-network1#type-variety": {
"value": "TNG3DAFS02"
},
"http://orange.thingin.ietf/ietf-network1#elt-index": {
"value": 1
},
"http://orange.thingin.ietf/ietf-network1#nominal-carrier-power": {
"value": -1
}
}
}
}
]
}
¶ SearchForPaths
| Name | Type | Notes |
|---|---|---|
| @kind | Enum | value: SearchForPaths |
| originIRI | String | mandatory |
| direction | Enum: AnyDirection, InBound, OutBound | mandatory |
| weightRelationshipPropertyName | String | optional |
| defaultWeight | number | mandatory |
| maxDepth | Integer | mandatory |
| maxWeight | number | mandatory |
Example
{
"originIRI": "http://stephanie/test/ifc-21UYPZ3orDNgXJ8lzqFnWD",
"direction":"AnyDirection",
"@kind":"SearchForPaths",
"defaultWeight":1,
"maxDepth":1,
"maxWeight":1
}
Return type :
| Name | Type |
|---|---|
| matches | Array of MatchingPath |
| stateTimestamp | date-time |
Example
{
"@kind": "MatchingPath",
"path": [
{
"@kind": "GraphTwinNode",
"uuid": "7c13ea15-07c1-4a1e-8f97-1fcd8d54a970",
"iri": "http://stephanie/test/ifc-21UYPZ3orDNgXJ8lzqFnWD",
"twinSpace": "http://stephanie/test/",
"types": [
"http://elite.polito.it/ontologies/dogont.owl#Room"
],
"properties": {
"http://orange-labs.fr/fog/ont/building.owl#localProjectedGeometry": {
"value": "POLYGON ((12.2251 21.6707 0.1, 10.3306 21.6707 0.1, 10.3306 20.3308 0.1, 12.2251 20.3308 0.1, 12.2251 21.6707 0.1))"
},
"http://www.w3.org/2006/vcard/ns#rev": {
"value": "2021-03-09T10:16:59.164Z"
},
"http://www.w3.org/2006/vcard/ns#prodid": {
"value": "hV1_TujkZDXc33KCnGux5SDO.ifc"
},
"http://www.w3.org/2006/vcard/ns#given-name": {
"value": "Entree (Cuisine)"
}
}
},
{
"@kind": "GraphTwinNode",
"uuid": "42ab3d4d-2833-4b64-8b23-7f4601382cdd",
"iri": "http://stephanie/test/ifc-1nxDRrsQHCnhEPZQ0_Mv4e",
"twinSpace": "http://stephanie/test/",
"types": [
"http://elite.polito.it/ontologies/dogont.owl#Storey"
],
"properties": {
"http://www.w3.org/2006/vcard/ns#rev": {
"value": "2021-03-09T10:16:59.164Z"
},
"http://www.w3.org/2006/vcard/ns#prodid": {
"value": "hV1_TujkZDXc33KCnGux5SDO.ifc"
},
"http://elite.polito.it/ontologies/dogont.owl#levelFromGround": {
"value": 0
},
"http://www.w3.org/2006/vcard/ns#given-name": {
"value": "Rez-de-chaussée (ACID00000001-0000-0000-0000-000000000000)"
}
}
},
{
"@kind": "GraphRelationship",
"uuid": "42339283",
"type": "http://elite.polito.it/ontologies/dogont.owl#contains",
"originIRI": "http://stephanie/test/ifc-1nxDRrsQHCnhEPZQ0_Mv4e",
"originUUID": "42ab3d4d-2833-4b64-8b23-7f4601382cdd",
"targetIRI": "http://stephanie/test/ifc-21UYPZ3orDNgXJ8lzqFnWD",
"targetUUID": "42ab3d4d-2833-4b64-8b23-7f4601382cdd",
"properties": {}
}
]
}
],
"stateTimestamp": "2024-05-31T08:38:24.211797977Z"
}
¶ SearchForShortestPaths
| Name | Type | Notes |
|---|---|---|
| @kind | Enum | value: SearchForShortestPaths |
| originIRI | String | mandatory |
| targetIRI | String | mandatory |
| direction | Enum: AnyDirection, InBound, OutBound | mandatory |
| weightRelationshipPropertyName | String | optional |
| defaultWeight | number | mandatory |
| maxKShortestPath | Integer | mandatory |
Example
{
"originIRI": "http://net-twins/HUAWEI_LANNION/HUAWEI_LANNION__ROADM__167773147",
"targetIRI":"http://net-twins/HUAWEI_LANNION/HUAWEI_LANNION__ROADM__167772650",
"direction":"AnyDirection",
"@kind":"SearchForShortestPaths",
"defaultWeight":1,
"maxKShortestPath":5
}
Return type :
| Name | Type |
|---|---|
| matches | Array of MatchingPath |
| stateTimestamp | date-time |
Example
{
"@kind": "MatchingPath",
"path": [
{
"@kind": "GraphTwinNode",
"uuid": "04a96e1e-1ee7-5c2f-9c37-7943d3206859",
"iri": "http://net-twins/HUAWEI_LANNION/HUAWEI_LANNION__ROADM__167773147",
"twinSpace": "http://net-twins/HUAWEI_LANNION/",
"types": [
"http://orange.thingin.ietf/ietf-network1#ROADM"
],
"properties": {
"http://orange.thingin.ietf/ietf-network1#name": {
"value": "NE(100-104)"
},
"http://orange.thingin.ietf/ietf-network1#ietf-te-topology:te-node-id": {
"value": "129.9.231.123"
},
"cG9z": {
"value": {
"coordinates": [
-2.399818,
47.934166
],
"type": "Point"
}
},
"http://orange.thingin.ietf/ietf-network1#node-id": {
"value": "167773147"
},
"http://www.opengis.net/gml/pos": {
"value": "{\"coordinates\": [-2.399818, 47.934166], \"type\": \"Point\"}"
}
}
},
{
"@kind": "GraphTwinNode",
"uuid": "d78149a6-0a53-5a14-ab23-f2900618774d",
"iri": "http://net-twins/HUAWEI_LANNION/HUAWEI_LANNION",
"twinSpace": "http://net-twins/HUAWEI_LANNION/",
"types": [
"http://orange.thingin.ietf/ietf-network1#Network"
],
"properties": {
"http://orange.thingin.ietf/ietf-network1#network-id": {
"value": "HUAWEI_LANNION"
}
}
},
{
"@kind": "GraphTwinNode",
"uuid": "46afc64a-043e-51c4-a0f1-d88c2d6cd612",
"iri": "http://net-twins/HUAWEI_LANNION/HUAWEI_LANNION__ROADM__167772650",
"twinSpace": "http://net-twins/HUAWEI_LANNION/",
"types": [
"http://orange.thingin.ietf/ietf-network1#ROADM"
],
"properties": {
"http://orange.thingin.ietf/ietf-network1#name": {
"value": "AGG1-M12"
},
"http://orange.thingin.ietf/ietf-network1#ietf-te-topology:te-node-id": {
"value": "129.9.98.100"
},
"cG9z": {
"value": {
"coordinates": [
-2.419225,
48.1947
],
"type": "Point"
}
},
"http://orange.thingin.ietf/ietf-network1#node-id": {
"value": "167772650"
},
"http://www.opengis.net/gml/pos": {
"value": "{\"coordinates\": [-2.419225, 48.1947], \"type\": \"Point\"}"
}
}
},
{
"@kind": "GraphRelationship",
"uuid": "a12427c6-de6f-4ab4-af31-78b6e632a60d",
"type": "http://orange.thingin.ietf/ietf-network1#has-roadm",
"originIRI": "http://net-twins/HUAWEI_LANNION/HUAWEI_LANNION",
"originUUID": "d78149a6-0a53-5a14-ab23-f2900618774d",
"targetIRI": "http://net-twins/HUAWEI_LANNION/HUAWEI_LANNION__ROADM__167773147",
"targetUUID": "d78149a6-0a53-5a14-ab23-f2900618774d",
"properties": {}
},
{
"@kind": "GraphRelationship",
"uuid": "935c70d8-de02-4027-9a9f-55ea93353797",
"type": "http://orange.thingin.ietf/ietf-network1#has-roadm",
"originIRI": "http://net-twins/HUAWEI_LANNION/HUAWEI_LANNION",
"originUUID": "d78149a6-0a53-5a14-ab23-f2900618774d",
"targetIRI": "http://net-twins/HUAWEI_LANNION/HUAWEI_LANNION__ROADM__167772650",
"targetUUID": "d78149a6-0a53-5a14-ab23-f2900618774d",
"properties": {}
}
]
}
],
"stateTimestamp": "2024-05-31T11:53:15.405686029Z"
}
¶ searchList ( POST /essentials/search/list )
Same syntax but with a returned list instead of a stream of elements