Introducing Essentials, an API designed to simplify Thing In operations, focusing on user experience and core functionalities in order to manage digital twins.
This section contains all the prerequisites you should know before you start using Essentials API.
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.
You can also find it in the Thing In user interface. (develop menu > Get my Thing in token)
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 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
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.
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.
Read the previous section to understand what twin spaces are made for.
Method | HTTP request | Description |
---|---|---|
twinsSpacesCreate | POST /essentials/twinsSpaces | Create a single twins space |
twinsSpacesDelete | DELETE /essentials/twinsSpaces/ID | Delete an twin space knowing its ID (uuid or iri) |
twinsSpacesGet | GET /essentials/twinsSpaces/ID | Get an twin space knowing its ID (uuid or iri) |
twinsSpacesList | GET /essentials/list/twinsSpaces | List twins spaces |
twinsSpacesStream | GET /essentials/twinsSpaces | List twins spaces in a continuous stream |
Create a single twins 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-twins-space",
"historized": true,
"multiRelationship": true,
"expireAfter": 9007199254740991
}
Return type :
Name | Type | Description |
---|---|---|
uuid | UUID | UUID of the created twin space |
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 |
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
}
List twins 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/twinsSpaces/{id})
List twins 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/twinsSpaces/{id})
Twin nodes are nodes of the Thing In graph. Check previous docs with "avatar" words for more.
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 |
Create a twin node.
Payload :
Name | Type | Description | Notes |
---|---|---|---|
iri | String | The unique twin node user-oriented identifier | mandatory |
classes | List<String> | The twin node semantic classes | optional |
labels | List<String> | The labels attached to this twin nodes | optional |
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",
"classes": [
"string"
],
"labels": [
"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"
}
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 |
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"
}
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"
}
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 |
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 | |
classes | List<String> | The twin node semantic classes | optional |
labels | List<String> | The labels attached to this twin nodes | optional |
ontologyInstance | Boolean | true if the twin node has be defined by an ontology | |
visibility | enum: Undefined, All, Tipod, Owner | visibility of the twin node | |
owner | String | The source identifier from which this twin node have been created | optional |
creationDate | Date | Creation date of the twin node | optional |
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",
"classes": [
"string"
],
"labels": [
"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"
}
}
List twin nodes.
Query parameters :
Name | Type | Description | Notes |
---|---|---|---|
twinsSpace | List<String> | optional | |
iri | String | optional | |
labels | List<String> | optional | |
classes | List<String> | optional | |
withOutgoingRelationship | Boolean | optional | |
ownerUUID | 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, with a maximum set to 1000 | optional |
Return type :
List of twin nodes (see GET /essentials/twinnodes/{id}).
List twin nodes in a continuous stream.
Query parameters :
Name | Type | Description | Notes |
---|---|---|---|
twinsSpace | List<String> | optional | |
iri | String | optional | |
labels | List<String> | optional | |
classes | List<String> | optional | |
withOutgoingRelationship | Boolean | optional | |
ownerUUID | 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, with a maximum set to 1000 | optional |
Return type :
Stream (json-seq) of twin nodes (see GET /essentials/twinNodes/{id})
Update a twin node.
Payload :
Name | Type | Description | Notes |
---|---|---|---|
classes | List | The twin node semantic classes | optional |
labels | List | The labels attached to this twin nodes | optional |
visibility | enum: Undefined, All, Tipod, Owner | mandatory | |
properties | Map<String, any> | mandatory |
{
"classes": [
"string"
],
"labels": [
"string"
],
"visibility": "All",
"properties": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}
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 |
Create a single relationship.
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"
}
}
Delete an relationship knowing its UUID.
Parameters :
Name | Type | Description | Notes |
---|---|---|---|
id | String | UUID of the relationship | mandatory in path |
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"
}
}
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})
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 |
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"
}
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"
}
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})
Update an relationship with their UUID.
Payload :
Name | Type |
---|---|
properties | Map<String, any> |
{
"properties": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}
Create or update an relationship.
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"
}
}
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 |
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"
}
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 |
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"
}
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"
}
]
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})
Update a label
Payload :
Name | Type |
---|---|
description | String |
{
"description": "string"
}
With the Tools API, you can get:
in order to make the switch easier with UUID. Try it out !