In this document, we will guide you through the process of using Acreto API to define a new Thing. To do this, we will:
Before you start, you will need to:
Our API follows the following conventions, standards and best practices:
This document describes API version 2. Our approach to versioning allows us to guarantee backward compatibility of APIs.
Production:
All examples in this document are constructed as curl
commands.
For convenience, the following environment variables are used in these
examples:
/auth/login
endpointUnless stated otherwise, each request sent to API should contain an access token in the “Authorization: Bearer” header. This token can be retrieved from /auth/login endpoint (see below).
Example of the header:
Authorization: Bearer GciiIUI1NiIsInR5cCI6IkpXVCJ9.JleHBpcnkiOjYwMCwicm9sZOiJmaW5hbmlX2FkbWlucy42NzxNjMyYi1iMzM3LTRjZDAtM2NiYy1lOTAwZTJjNzdmYTMgc3VwZXJZG1pbnMuNjc0MTYzMmItYjMzNy00Y2QNjYmMtZTkwMGUyYzc3ZmEzIiwic2VjanVLMVpSM2dvVmowNFRwSFRFSkJXS3giLCJ1c2VybmFtZSI6ImxrbGltZWsrZG9jQGdtYWlsLmNvbSIsInV1aWQiOiMS1kMDU4LTBjMzYtZGU2NS1lZmY0MWUwY2EwNjMifQ.YR7Vm8ys2p3NHJs65QymqBPJ52lsnOXcxj_1WSbyMh0
The token has set an expiration time, set to 600 seconds by default. When the token expires, the API request will fail with HTTP status 401. Your application should detect such a situation, retrieve a new token and retry the failed request.
Coming soon: Expiry time will be exposed as part of the response to
/auth/login request, as expiry
field.
To handle updates, we use HTTP PUT method. Unless stated otherwise, PUT replaces the resource in its entirety. It means that:
One important exception here is updating credentials (like passwords), which usually has its own endpoint. See API documentation for details.
Acreto Platform relies on a transactional model. Changes introduced to an ecosystem are not applied immediately; you need to commit them first.
Ecosystem object contains status
field. You should avoid doing any changes to the ecosystem which is in status different than:
ok
pending_changes
executed, and you should re-check the status later.
Another interesting status is commit_in_progress
. It means commit is being
If the ecosystem gets into ecosystem_error
status, please contact support.
To retrieve access token, you need to send your username and password to /auth/login endpoint.
Request:
curl -X POST -H 'Content-type: application/json' ${ENDPOINT}/auth/login -d "{\"username\":\"$USERNAME\",\"password\":\"$PASSWORD\"}" | jq .
Response:
{
"accessToken": "bGciOiJIUzI1NiIsCI6IkpXVCJ9.aW5hbmNlX2FkbWlucy42NzQxNMuNjc0MTYzMmItYjMzNy00Y2QwLTNjYmMtNFRwSFRFSkJXS3giLCJ1c2VybmFtZSI6ImxrbGltZTBjMzYtZGU2NS1lZmwNjMifQ.YR72lsnOXcxj_1WSbyMh0",
"customers": [
{
"name": "Documentation",
"uuid": "6741632b-b337-4cd0-3cbc-e900e2c77fa3"
}
]
}
Put the content of accessToken
into TOKEN
environment variable and customer
uuid into CUSTOMERUUID
environment variable for future reference.
TOKEN="bGciOiJIUzI1NiIsCI6IkpXVCJ9.aW5hbmNlX2FkbWlucy42NzQxNMuNjc0MTYzMmItYjMzNy00Y2QwLTNjYmMtNFRwSFRFSkJXS3giLCJ1c2VybmFtZSI6ImxrbGltZTBjMzYtZGU2NS1lZmwNjMifQ.YR72lsnOXcxj_1WSbyMh0"
CUSTOMERUUID="6741632b-b337-4cd0-3cbc-e900e2c77fa3"
To list ecosystems owned by the customer, run GET requests against ecosystems endpoint.
Request:
curl -X GET -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" ${ENDPOINT}/customers/$CUSTOMERUUID/ecosystems|jq .
Response:
[
{
"created": "2020-09-30T10:24:00.000Z",
"name": "Documentation Ecosystem",
"nsps": [
{
"name": "EWR1",
"status": "green"
}
],
"owner": {
"fullName": "John Doe",
"username": "someone@somedomain.com",
"uuid": "5fdb6311-d058-0c36-de65-eff41e0ca063"
},
"status": "pending_changes",
"uuid": "049d6701-a8d3-ca61-662e-3f6adbbd4156"
}
]
Save ecosystem UUID into ECOSYSTEMUUID
environment variable for future
reference.
ECOSYSTEMUUID=049d6701-a8d3-ca61-662e-3f6adbbd4156
To create a Thing, we will need a Profile Group. Fortunately, first Profile Group is created automatically, so we just need to list them and get group UUID.
Request:
curl -X GET -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" ${ENDPOINT}/customers/$CUSTOMERUUID/ecosystems/$ECOSYSTEMUUID/groups|jq .
Response:
[
{
"name": "Profile Group 1",
"uuid": "06f93ee9-3153-3111-8150-01b3d5389106"
}
]
Save profile group UUID to GROUPUUID
environment variable for future reference.
GROUPUUID="06f93ee9-3153-3111-8150-01b3d5389106"
To create a Thing, we will send POST request to devices
endpoint.
Request:
curl -X POST -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" ${ENDPOINT}/customers/$CUSTOMERUUID/ecosystems/$ECOSYSTEMUUID/devices -d "{\"name\":\"My first Thing\", \"type\": \"device\",\"category\":\"IoT\",\"assetValue\":1, \"profileGroup\": \"$GROUPUUID\" }"
Response:
{
"assetValue": 1,
"category": "IoT",
"expiry": {
"time": "0001-01-01T00:00:00.000Z",
"type": ""
},
"name": "My first Thing",
"profileGroup": "06f93ee9-3153-3111-8150-01b3d5389106",
"type": "device",
"uuid": "c86c8910-1770-818b-a0c8-cf9d91201255"
}
Save Thing UUID to THINGUUID
environment variable for future reference.
THINGUUID="c86c8910-1770-818b-a0c8-cf9d91201255"
To ensure that the Thing was created successfully, we will try to read it.
Request:
curl -X GET -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" ${ENDPOINT}/customers/$CUSTOMERUUID/ecosystems/$ECOSYSTEMUUID/devices/$THINGUUID
Response:
{
"assetValue": 1,
"category": "IoT",
"expiry": {
"time": "0001-01-01T00:00:00.000Z",
"type": ""
},
"name": "My first Thing",
"profileGroup": "06f93ee9-3153-3111-8150-01b3d5389106",
"type": "device",
"uuid": "c86c8910-1770-818b-a0c8-cf9d91201255"
}
As you see, the Thing has been created successfully. To get it working, we need to commit our changes.
To commit changes, we’ll send an empty POST request to commits endpoint.
Request:
curl -X POST -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" ${ENDPOINT}/customers/$CUSTOMERUUID/ecosystems/$ECOSYSTEMUUID/commits
Response: none
Now, we need to monitor status of the ecosystem to see when commit is done. For new ecosystems, it can take several minutes.
We’ll repeat a GET request to read the ecosystem in a loop, until ecosystem
status changes from commit_in_progress
to ok
.
Request:
curl -X GET -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" ${ENDPOINT}/customers/$CUSTOMERUUID/ecosystems/$ECOSYSTEMUUID
Response:
{
"created": "2020-09-30T10:24:00.000Z",
"name": "Documentation Ecosystem",
"nsps": [
{
"name": "EWR1",
"status": "green"
}
],
"owner": {
"fullName": "John Doe",
"username": "someone@somedomain.com",
"uuid": "5fdb6311-d058-0c36-de65-eff41e0ca063"
},
"status": "commit_in_progress",
"uuid": "049d6701-a8d3-ca61-662e-3f6adbbd4156"
}
In this document, we went through a process of creating new Thing inside an ecosystem.