Link Search Menu Expand Document
NulvaDoc

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

The NuvlaEdge Agent API

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

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

This ensures that whatever new micro-services are added to the NuvlaEdge, 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 NuvlaEdge as a micro-service, and you need to interact with Nuvla, you need to use the NuvlaEdge Agent API as follows:

REST API

The NuvlaEdge Agent API can only be reached from inside the NuvlaEdge!

  • 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 NuvlaEdge

allowed:
POST
/api/commission

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

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

However, if you must use it, you’ll need to POST a JSON payload compliant with the NuvlaEdge 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
}