API Quick start

Introduction

Overview

In this document, we will guide you through the process of using Acreto API to define a new Thing. To do this, we will:

  1. Authenticate to get an access token
  2. List ecosystems to find the one we will use
  3. List Profile Groups to find the one we will use
  4. Create a new Thing
  5. Read the Thing to ensure it was created
  6. Commit changes

Prerequisites

Before you start, you will need to:

Conventions

Our API follows the following conventions, standards and best practices:

API versioning

This document describes API version 2. Our approach to versioning allows us to guarantee backward compatibility of APIs.

API endpoints

Production:

Environment varialbles

All examples in this document are constructed as curl commands. For convenience, the following environment variables are used in these examples:

  • ENDPOINT=https://api-is-rock-solid.acreto.net/v2
  • USERNAME=someone@somedomain.com
  • PASSWORD=************
  • TOKEN - access token retrieved from /auth/login endpoint
  • CUSTOMERUUID - ID of customer (organization) account
  • ECOSYSTEMUUID - ID of the ecosystem to be used

API basics

Authentication

Unless 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.

Object updates

To handle updates, we use HTTP PUT method. Unless stated otherwise, PUT replaces the resource in its entirety. It means that:

  • any update operation MUST contain all fields of the resource,
  • sending PUT request without some field will either remove it from the resource or set it to “zero value”.

One important exception here is updating credentials (like passwords), which usually has its own endpoint. See API documentation for details.

Commits

Acreto Platform relies on a transactional model. Changes introduced to an ecosystem are not applied immediately; you need to commit them first.

Ecosystem status

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.

Creating the Thing

Login to get access token

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"

List ecosystems and select the one to use

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

List Profile Groups

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"

Create a Thing

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"

Read the Thing

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.

Commit 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

Monitor ecosystem status to see commit progress

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"
}

Summary

In this document, we went through a process of creating new Thing inside an ecosystem.