Link

Before you start contributing to the NuvlaBox software stack, you must be acquainted not only with the NB and NBE architectures and features, but also with the internal functionalities offered specifically for allowing the interaction between NBE micro-services.

The NBE Agent API

As mentioned in the NBE Architecture, the NBE Agent is one of the most critical components of the NB.

All outgoing communication to Nuvla pass through the agent. For that, it provides an internal REST API for other NBE micro-services to speak with when they need to reach out to Nuvla.

This ensures that whatever new micro-services are added to the NB, they won’t need to manipulate Nuvla credentials in order to reach out to Nuvla. Instead, the agent will validate and broker their requests, sanitizing whatever information is being passed.

So in short, if you are building a new component that will run alongside the NBE as a micro-service, and you need to interact with Nuvla, you need to use the NBE Agent API as follows:

REST API

The NBE Agent API can only be reached from inside the NuvlaBox!

  • If your micro-service is running on the same local Docker network as the agent (typically this network is called nuvlabox_default, otherwise you can double check its name by running docker network ls), then you can reach the API at http://agent/api

or,

  • if your micro-service is running in host mode (same network scope as any other process on the host device), then you can reach the API at http://127.0.0.1:5080

Get agent healthcheck

allowed:
GET
/api/healthcheck

Returns something if the agent and respective API are already up and running. This call is meant to be used as a healthcheck for other components that are waiting for the agent to be ready.

Examples:

GET
/api/healthcheck

curl --fail -X GET http://agent/api/healthcheck
Response:
true

Re-commission the NuvlaBox

allowed:
POST
/api/commission

It might happen that due to a change in the NuvlaBox or a need to refresh certain credentials and/or system configurations, the NuvlaBox needs to be re-commissioned so that Nuvla can propagate the new changes. This call will trigger a NuvlaBox re-commissioning, according to the request payload.

This call is tailored to be used by specific NuvlaBox components like the Network Manager.

However, if you must use it, you’ll need to POST a JSON payload compliant with the NuvlaBox commission schema described here.

Examples:

POST
/api/commission

curl --fail -X POST http://agent/api/commission -H content-type:application/json -d '{"swarm-token-manager": "xyzNewTokenxyz"}'
Response:
true

Manage a peripheral

allowed:
GET
POST
PUT
DELETE
/api/peripheral/

Provides reading and editing capabilities for peripherals.

Examples:

Get a list of all peripheral identifiers already registered:

GET
/api/peripheral

curl --fail -X GET http://agent/api/peripheral
Response:
["18ec:3399","0424:2514","1d6b:0002","0424:7800"]


Get the description of a specific peripheral, by identifier:

GET
/api/peripheral/`identifier`

  curl --fail -X GET http://agent/api/peripheral/0424:7800
Response:
{
  "available": true,
  "classes": [
    "Vendor Specific Class"
  ],
  "description": "USB 0424:7800 Standard Microsystems Corp. ",
  "device-path": "/dev/bus/usb/001/004",
  "id": "nuvlabox-peripheral/3448e2e7-a035-4c48-9301-a13dea2d621f",
  "identifier": "0424:7800",
  "interface": "USB",
  "name": "USB 0424:7800 Standard Microsystems Corp. ",
  "parent": "nuvlabox/6bf5af32-d003-405c-8d6a-f678346693f3",
  "vendor": "Standard Microsystems Corp. ",
  "version": 1
}


Add a new peripheral:

POST
/api/peripheral

curl --fail -X POST http://agent/api/peripheral -H content-type:application/json -d '{"identifier": "test", "classes": ["test-class"], "available": true}'
Response:
{
  "message": "nuvlabox-peripheral/2613f093-a8bf-413f-b2c9-1310d3440aa5 created",
  "resource-id": "nuvlabox-peripheral/2613f093-a8bf-413f-b2c9-1310d3440aa5",
  "status": 201
}


Search for a peripheral by attribute:

GET
/api/peripheral?

curl --fail -X GET 'http://agent/api/peripheral?parameter=identifier&value=test'
Response:
{
  "test": {
    "available": true,
    "classes": [
      "test-class"
    ],
    "id": "nuvlabox-peripheral/2613f093-a8bf-413f-b2c9-1310d3440aa5",
    "identifier": "test",
    "parent": "nuvlabox/6bf5af32-d003-405c-8d6a-f678346693f3",
    "version": 1
  }
}


Search for a peripheral by identifier regex:

GET
/api/peripheral?

curl --fail -X GET 'http://agent/api/peripheral?identifier_pattern=0*:*'
Response:
{
  "0424:2514": {
    "available": true,
    "classes": [
      "Hub"
    ],
    "description": "USB 0424:2514 Standard Microsystems Corp. USB 2.0 Hub ",
    "device-path": "/dev/bus/usb/001/003",
    "id": "nuvlabox-peripheral/3037997b-1f1d-4ed1-bddb-10b52c52adba",
    "identifier": "0424:2514",
    "interface": "USB",
    "name": "USB 2.0 Hub ",
    "parent": "nuvlabox/6bf5af32-d003-405c-8d6a-f678346693f3",
    "product": "USB 2.0 Hub ",
    "vendor": "Standard Microsystems Corp. ",
    "version": 1
  },
  "0424:7800": {
    "available": true,
    "classes": [
      "Vendor Specific Class"
    ],
    "description": "USB 0424:7800 Standard Microsystems Corp. ",
    "device-path": "/dev/bus/usb/001/004",
    "id": "nuvlabox-peripheral/3448e2e7-a035-4c48-9301-a13dea2d621f",
    "identifier": "0424:7800",
    "interface": "USB",
    "name": "USB 0424:7800 Standard Microsystems Corp. ",
    "parent": "nuvlabox/6bf5af32-d003-405c-8d6a-f678346693f3",
    "vendor": "Standard Microsystems Corp. ",
    "version": 1
  }
}


Edit an existing peripheral

PUT
/api/peripheral/`identifier`

curl --fail -X PUT http://agent/api/peripheral/test -H content-type:application/json -d '{"available": false}'
Response:
{
  "acl": {
    "delete": [
      "group/nuvla-admin"
    ],
    "edit-acl": [
      "group/nuvla-admin"
    ],
    "edit-data": [
      "group/nuvla-admin"
    ],
    "edit-meta": [
      "group/nuvla-admin"
    ],
    "manage": [
      "group/nuvla-admin",
      "infrastructure-service/eb8e09c2-8387-4f6d-86a4-ff5ddf3d07d7",
      "user/ef5cddf8-5d70-4c29-89ff-079ef7f90976"
    ],
    "owners": [
      "nuvlabox/6bf5af32-d003-405c-8d6a-f678346693f3"
    ],
    "view-acl": [
      "group/nuvla-admin",
      "infrastructure-service/eb8e09c2-8387-4f6d-86a4-ff5ddf3d07d7",
      "user/ef5cddf8-5d70-4c29-89ff-079ef7f90976"
    ],
    "view-data": [
      "group/nuvla-admin",
      "infrastructure-service/eb8e09c2-8387-4f6d-86a4-ff5ddf3d07d7",
      "user/ef5cddf8-5d70-4c29-89ff-079ef7f90976"
    ],
    "view-meta": [
      "group/nuvla-admin",
      "infrastructure-service/eb8e09c2-8387-4f6d-86a4-ff5ddf3d07d7",
      "user/ef5cddf8-5d70-4c29-89ff-079ef7f90976"
    ]
  },
  "available": false,
  "classes": [
    "test-class"
  ],
  "created": "2021-01-13T16:02:12.276Z",
  "created-by": "nuvlabox/6bf5af32-d003-405c-8d6a-f678346693f3",
  "id": "nuvlabox-peripheral/2613f093-a8bf-413f-b2c9-1310d3440aa5",
  "identifier": "test",
  "parent": "nuvlabox/6bf5af32-d003-405c-8d6a-f678346693f3",
  "resource-type": "nuvlabox-peripheral",
  "updated": "2021-01-13T16:54:58.757Z",
  "updated-by": "nuvlabox/6bf5af32-d003-405c-8d6a-f678346693f3",
  "version": 1
}


Delete an existing peripheral

DELETE
/api/peripheral/`identifier`

curl --fail -X DELETE http://agent/api/peripheral/test
Response:
{
  "message": "nuvlabox-peripheral/2613f093-a8bf-413f-b2c9-1310d3440aa5 deleted",
  "resource-id": "nuvlabox-peripheral/2613f093-a8bf-413f-b2c9-1310d3440aa5",
  "status": 200
}

Copyright 2021, SixSq