Link
NuvlaDocs

Documentation for: the Nuvla.io edge management platform, based on the Nuvla edge to cloud open source software and the NuvlaBox open source edge and IoT runtime. Created with love by SixSq in Switzerland.


This site uses Just the Docs, a documentation theme for Jekyll.

Search

REST API

Nuvla provides a uniform and extensible HTTP-based RESTful API, for the management of Nuvla resources. A Nuvla resource can be anything you can perform an action on, through Nuvla, like your own user profile, a Nuvla application, credentials, etc.

Users have at their disposal all the usual CRUD (Create, Read, Update, Delete) operations, plus Searching and Querying.

Action HTTP Method Target
Search GET or PUT resource collection
Add (create) POST resource collection
Read GET resource
Edit (update) PUT resource
Delete DELETE resource

Finally, due to its versatility, Nuvla’s API also provide custom operations for certain resources. These will be covered individually in the subsections below.

Here are a few examples on how to construct the different HTTP requests:

  • GET all the resources of a specific type:

    GET /api/<resource-name>

  • GET a specific resource:

    GET /api/<resource-name>/<resource-uuid>

  • CREATE a new resource:

    POST       /api/<resource-name>
  HEADERS  Content-type:application/json
  DATA     <JSON resource>

  • EDIT an existing resource:

    PUT        /api/<resource-name>/<resource-uuid>
  HEADERS  Content-type:application/json
  DATA     <JSON with the attribute name and value to be changed>

  • DELETE a resource:

    DELETE /api/<resource-name>/<resource-uuid>

Understanding the Nuvla REST API output format

All the Nuvla API calls will return a JSON output, and you’ll notice that all of these outputs contain a set of common attributes:

  • id: unique resource identifier, defined by the API server
  • acl: fine-grained access-control list, used for managing authorization process for each resource and its collections of resources. If not defined by the user, the API server will default it based on the requesting user credentials.
  • created: timestamp of creation, defined by the API server
  • updated: timestamp of the last update, defined by the API server
  • resource-type: type of resource, defined by the API server
  • operations: set of available operations for that resource, defined by the API server
  • name: optional user-friendly name for a specific resource, defined by the user or defaulted to None if undefined
  • description: optional verbose description for a specific resource, defined by the user or defaulted to None if undefined

API Syntax

The Nuvla REST API endpoints are constructed with the following pattern:

/api/<resource-name>/<resource-uuid>/<action>/

where

  • <resource-name> is the Kebab Case name of the resource collection you’re accessing,
  • <resource-uuid> is the unique identifier for the specific resource you’re managing,
  • <action> is a custom additional operation that might be allowed for that resource.

On top of that, Nuvla’s REST API also offers searching and querying through a parameter-based set of keywords:

/api/<resource-name>?param=value&param=value...

where

Parameter Description Examples
filter Used to return only the set of resources that have an attribute matching a certain value ?filter=name="my-resource"

?filter=people/gender!="male" and people/age>=21

?filter=application-name^="my-app-"
orderby To order the returned resources by the specified attribute ?orderby=created:desc

?orderby=people/surname:asc
aggregation On top of the requested resources, it will also return on-the-fly aggregations based on the specified function. Available functions: avg, max, min, sum, cardinality, terms, stats, extendedstats, percentiles, count, missing ?aggregation=avg:people/age
last and first Returns a range of resources by setting the first and last (1-based) query parameters ?first=10&last=20
select Selects only certain attributes to be returned by the server. Avoiding sending information that will not be useful reduces the load on the network and the server ?select=people/id

Resources

Resources are managed individually, which means that the data schemas and available operations might defer from one to the other. These options are all explained and exemplified in the following sections.

cloud-entry-point

allowed:
GET
/api/cloud-entry-point

The primary directory of resources is the Cloud Entry Point (CEP), which contains a list of named resource collections and their URLs (in the href field) relative to the baseURI value. The CEP also contains some other metadata.

The endpoint is accessible for all registered and anonymous Nuvla users.

Examples

Get the cloud entry point
GET
/api/cloud-entry-point 

curl https://nuvla.io/api/cloud-entry-point
Response: 
{
  "acl" : {
    "view-acl" : [ "group/nuvla-anon" ],
    "view-meta" : [ "group/nuvla-anon" ],
    "view-data" : [ "group/nuvla-anon" ],
    "owners" : [ "group/nuvla-admin" ]
  },
  "id" : "cloud-entry-point",
  "resource-type" : "cloud-entry-point",
  "created" : "2019-06-24T13:01:15.720Z",
  "updated" : "2019-06-24T13:01:15.720Z",
  "base-uri" : "https://nuvla.io/api/",
  "collections" : {
    "nuvlabox" : {
      "href" : "nuvlabox"
    },
    "module-application" : {
      "href" : "module-application"
    },
    "session-template" : {
      "href" : "session-template"
    },
    "email" : {
      "href" : "email"
    },
    "cloud-entry-point" : {
      "href" : "cloud-entry-point"
    },
    "group" : {
      "href" : "group"
    },
    "infrastructure-service-template" : {
      "href" : "infrastructure-service-template"
    },
    "resource-metadata" : {
      "href" : "resource-metadata"
    },
    "data-record" : {
      "href" : "data-record"
    },
    "data-object" : {
      "href" : "data-object"
    },
    "user-identifier" : {
      "href" : "user-identifier"
    },
    "notification" : {
      "href" : "notification"
    },
    "infrastructure-service" : {
      "href" : "infrastructure-service"
    },
    "credential" : {
      "href" : "credential"
    },
    "data-object-public" : {
      "href" : "data-object-public"
    },
    "credential-template" : {
      "href" : "credential-template"
    },
    "data-record-key-prefix" : {
      "href" : "data-record-key-prefix"
    },
    "data-object-generic" : {
      "href" : "data-object-generic"
    },
    "configuration-template" : {
      "href" : "configuration-template"
    },
    "module-component" : {
      "href" : "module-component"
    },
    "module" : {
      "href" : "module"
    },
    "nuvlabox-peripheral" : {
      "href" : "nuvlabox-peripheral"
    },
    "voucher-report" : {
      "href" : "voucher-report"
    },
    "data-object-template" : {
      "href" : "data-object-template"
    },
    "infrastructure-service-group" : {
      "href" : "infrastructure-service-group"
    },
    "event" : {
      "href" : "event"
    },
    "user-template" : {
      "href" : "user-template"
    },
    "deployment-log" : {
      "href" : "deployment-log"
    },
    "deployment" : {
      "href" : "deployment"
    },
    "group-template" : {
      "href" : "group-template"
    },
    "data-record-key" : {
      "href" : "data-record-key"
    },
    "configuration" : {
      "href" : "configuration"
    },
    "deployment-parameter" : {
      "href" : "deployment-parameter"
    },
    "voucher" : {
      "href" : "voucher"
    },
    "nuvlabox-status" : {
      "href" : "nuvlabox-status"
    },
    "evidence-record" : {
      "href" : "evidence-record"
    },
    "callback" : {
      "href" : "callback"
    },
    "data-set" : {
      "href" : "data-set"
    },
    "user" : {
      "href" : "user"
    },
    "session" : {
      "href" : "session"
    },
    "job" : {
      "href" : "job"
    }
  }
}

credential

allowed:
POST
GET
PUT
DELETE
/api/credential/uuid

The credential resource is used to save all the credentials necessary to manage your Nuvla resources. From API keys, to Container Orchestration Engine credentials, TLS certificates, etc. Most of the credentials are expected to be provided by the user, some are generated by Nuvla (e.g. API key).

Examples

Generate an API key credential
POST
/api/credential 

curl -XPOST https://nuvla.io/api/credential -H 'content-type:application/json' -b cookies -d '
{
  "template": {
    "method": "generate-api-key",
    "ttl": 0,
    "href": "credential-template/generate-api-key"
  }
}
'
Response: 
{
  "status" : 201,
  "message" : "credential/<key_uuid> created",
  "resource-id" : "credential/<key_uuid>",
  "secret-key" : "<secret>"
}
Docker Swarm token credential
POST
/api/credential 

curl -XPOST https://nuvla.io/api/credential -H 'content-type:application/json' -b cookies -d '
{
  "template": {
    "parent": "infrastructure-service/<UUID of your Docker Swarm Infrastructure in Nuvla>",
    "method": "swarm-token",
    "href": "credential-template/swarm-token",
    "scope": "WORKER | MANAGER",
    "token": "abcs1234token"
  }
}
'
Response: 
{
  "status" : 201,
  "message" : "credential/92dc58ce-15c2-4140-acc9-cff07ea47ba5 created",
  "resource-id" : "credential/92dc58ce-15c2-4140-acc9-cff07ea47ba5"
}
Infrastructure Service S3 credential
POST
/api/credential 

curl -XPOST https://nuvla.io/api/credential -H 'content-type:application/json' -b cookies -d '
{
  "name": "S3 credential",
  "description": "S3 credential",
  "template": {
    "href": "credential-template/infrastructure-service-minio",
    "parent": "infrastructure-service/<UUID of the S3 Infrastructure in Nuvla>",
    "access-key": "",
    "secret-key": ""
  }
}
'
Response: 
{
  "status" : 201,
  "message" : "credential/992fd969-d14b-4d55-967a-094bbae5fc1a created",
  "resource-id" : "credential/992fd969-d14b-4d55-967a-094bbae5fc1a"
}
Infrastructure Service Docker Swarm HTTP API credential
POST
/api/credential 

curl -XPOST https://nuvla.io/api/credential -H 'content-type:application/json' -b cookies -d '''
{
    "name": "Docker Swarm",
    "description": "Docker Swarm",
    "template": {
        "href": "credential-template/infrastructure-service-swarm"
        "parent": "infrastructure-service/<UUID of the Docker Swarm Infrastructure in Nuvla>",
        "key": "client-private-certificate",
        "ca": "ca-public-certificate",
        "cert": "client-public-certificate",
    }
}
'''
Response: 
{
  "status" : 201,
  "message" : "credential/530f1429-fd41-41e9-9956-38c27db0ebd5 created",
  "resource-id" : "credential/530f1429-fd41-41e9-9956-38c27db0ebd5"
}
Infrastructure Service Kubernetes HTTP API credential
POST
/api/credential 

curl -XPOST https://nuvla.io/api/credential -H 'content-type:application/json' -b cookies -d '
{
  "name": "Kubernetes",
  "description": "Kubernetes",
  "template": {
    "parent": "infrastructure-service/<UUID of the Kubernetes Infrastructure in Nuvla>",
    "href": "credential-template/infrastructure-service-swarm"
    "key": "client-private-certificate",
    "ca": "ca-public-certificate",
    "cert": "client-public-certificate",
  }
}
'
Response: 
{
  "status" : 201,
  "message" : "credential/130f1429-fd41-41e9-9956-38c27db0ebd0 created",
  "resource-id" : "credential/130f1429-fd41-41e9-9956-38c27db0ebd0"
}

deployment

allowed:
POST
GET
PUT
DELETE
/api/deployment/uuid

The deployment resource allows you to deploy an instance of a module.

Examples

Start/Stop an application
POST
PUT
GET
/api/deployment 

# Initialize a deployment by creating an instance of module/<uuid>
ID=$(curl -X POST -s https://nuvla.io/api/deployment -H 'content-type: application/json' -b ~/cookies -d '''
    {
        "module": {
            "href": "module/<uuid>"
        }
    }
''' | jq -r '."resource-id"')

# Retain the ID of the created instance
echo ${ID}

# Associate an infrastructure credential with that instance
curl -X PUT https://nuvla.io/api/${ID} -H 'content-type: application/json' -b cookies -d '''
    {
        "parent": "credential/<uuid>"
    }
'''

# Start the deployment
curl https://nuvla.io/api/${ID}/start -b cookies

# Stop the deployment
curl https://nuvla.io/api/${ID}/stop -b cookies
Response: 
{
  "status": 201,
  "message": "deployment/38401e41-25ea-4f45-a3b1-456df8d71918 created",
  "resource-id": "deployment/38401e41-25ea-4f45-a3b1-456df8d71918"
}

{
  "parent" : "credential/<uuid>",
  "updated" : "2019-10-29T12:35:33.308Z",
  "created" : "2019-10-29T12:30:53.296Z",
  "state" : "CREATED",
  "api-endpoint" : "https://nuvla.io",
  "module" : {
    "description" : "Example of the things you can do with Nuvla",
    "path" : "yourspace/random/things-you-can-do-with-nuvla",
    "content" : {
      "urls" : [ [ "My App", "http://192.168.43.192/" ] ],
      "updated" : "2019-10-17T09:53:53.414Z",
      "created" : "2019-10-17T09:53:53.414Z",
      "output-parameters" : [ ],
      "author" : "Bruce Wayne",
      "id" : "module-application/<uuid>",
      "commit" : "no commit message",
      "docker-compose" : "version: '3'\n\nservices:\n  blinkt:\n    image: hello-world\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock\n    deploy:\n      placement:\n        constraints:\n          - node.role == manager"
    },
    "updated" : "2019-10-17T09:53:53.432Z",
    "name" : "THINGS YOU CAN DO WITH NUVLA",
    "created" : "2019-10-17T09:53:53.432Z",
    "parent-path" : "yourspace/random",
    "data-accept-content-types" : [ ],
    "id" : "module/<uuid>",
    "resource-type" : "module",
    "acl" : {
      "edit-data" : [ "group/nuvla-admin" ],
      "owners" : [ "user/<uuid>" ],
      "view-acl" : [ "group/nuvla-admin" ],
      "delete" : [ "group/nuvla-admin" ],
      "view-meta" : [ "group/nuvla-admin" ],
      "edit-acl" : [ "group/nuvla-admin" ],
      "view-data" : [ "group/nuvla-admin" ],
      "manage" : [ "group/nuvla-admin" ],
      "edit-meta" : [ "group/nuvla-admin" ]
    },
    "logo-url" : "https://cdn.pixabay.com/photo/2019/08/20/12/12/lego-4418625_960_720.png",
    "href" : "module/<uuid>",
    "subtype" : "application"
  },
  "id" : "deployment/38401e41-25ea-4f45-a3b1-456df8d71918",
  "api-credentials" : {
    "api-key" : "credential/<key_uuid>",
    "api-secret" : "secret"
  },
  "resource-type" : "deployment",
  "acl" : {
    "edit-data" : [ "group/nuvla-admin" ],
    "owners" : [ "user/<uuid>" ],
    "view-acl" : [ "group/nuvla-admin" ],
    "delete" : [ "group/nuvla-admin" ],
    "view-meta" : [ "group/nuvla-admin" ],
    "edit-acl" : [ "group/nuvla-admin" ],
    "view-data" : [ "group/nuvla-admin" ],
    "manage" : [ "group/nuvla-admin" ],
    "edit-meta" : [ "group/nuvla-admin" ]
  }
}

{
  "status" : 202,
  "message" : "starting deployment/38401e41-25ea-4f45-a3b1-456df8d71918 with async job/2b0b6058-6f7e-4d59-8f09-8ae30cfbdce9",
  "resource-id" : "deployment/38401e41-25ea-4f45-a3b1-456df8d71918",
  "location" : "job/2b0b6058-6f7e-4d59-8f09-8ae30cfbdce9"
}

evidence-record

allowed:
POST
GET
PUT
DELETE
/api/evidence-record/uuid

The evidence-record resource allows you to create and manage audit evidence records that can afterwards help you keep track of your infrastructures’ compliance to certain standards and certification schemas.

Examples

Create an evidence record
POST
/api/evidencerecord 

curl -XPOST https://nuvla.io/api/evidence-record -H 'content-type:application/json' -b cookies -d '''
{
	"end-time": "2018-06-20T11:34:52.555Z",
	"class" : "de.who.class.type.checks.location.GeoIPResult",
	"start-time" : "2018-06-21T11:34:52.000Z",
	"plan-id" : "abcde",
 	"passed" : true
}
'''
Response: 
{
  "status" : 201,
  "message" : "evidence-record/270cc74e-91be-4415-9e1c-eb137a37a0e4 created",
  "resource-id" : "evidence-record/270cc74e-91be-4415-9e1c-eb137a37a0e4"
}

infrastructure-service

allowed:
POST
GET
PUT
DELETE
/api/infrastructure-service/uuid

The infrastructure-service resource represents any manageable service with a working endpoint. This resource is templated, which means, like session and credential, you can also create infrastructure-services of different types.

Examples

Create Docker Swarm infrastructure service
POST
/api/infrastructure-service-swarm 

curl -XPOST https://nuvla.io/api/infrastructure-service -H 'content-type:application/json' -b cookies -d '
{
  "template": {
    "name": "Docker swarm",
    "description": "Docker swarm",
    "parent": "infrastructure-service-group/<UUID of your IS group>",
    "subtype": "swarm",
    "href": "infrastructure-service-template/generic",
    "endpoint": "https://service.example.org:1234"
  }
}
'
Response: 
{
  "status" : 201,
  "message" : "infrastructure-service/5b65b608-b362-4053-bdda-6088f60109b1 created",
  "resource-id" : "infrastructure-service/5b65b608-b362-4053-bdda-6088f60109b1"
}
Create Kubernetes infrastructure service
POST
/api/infrastructure-service 

curl -XPOST https://nuvla.io/api/infrastructure-service -H 'content-type:application/json' -b cookies -d '''
{
    "template": {
        "name": "Kubernetes",
        "description": "Kubernetes",
        "parent": "infrastructure-service-group/<UUID of your IS group>",
        "subtype": "kubernetes",
        "href": "infrastructure-service-template/generic",
        "endpoint": "https://service.example.org:1234"
    }
}
'''
Response: 
{
  "status" : 201,
  "message" : "infrastructure-service/5b65b608-b362-4053-bdda-6088f60109b1 created",
  "resource-id" : "infrastructure-service/5b65b608-b362-4053-bdda-6088f60109b1"
}
Create S3 infrastructure service
POST
/api/infrastructure-service 

curl -XPOST https://nuvla.io/api/infrastructure-service -H 'content-type:application/json' -b cookies -d '''
{
  "template": {
    "name": "S3",
    "description": "S3",
    "parent": "infrastructure-service-group/<UUID of your IS group>",
    "subtype": "s3",
    "href": "infrastructure-service-template/generic",
    "endpoint": "https://service.example.org:1234"
  }
}
'
Response: 
{
  "status" : 201,
  "message" : "infrastructure-service/2b65b608-b362-4053-bdda-6088f60109b3 created",
  "resource-id" : "infrastructure-service/2b65b608-b362-4053-bdda-6088f60109b3"
}
Create generic infrastructure service
POST
/api/infrastructure-service 

curl -XPOST https://nuvla.io/api/infrastructure-service -H 'content-type:application/json' -b cookies -d '
{
  "template": {
    "name": "Generic",
    "description": "Generic",
    "parent": "infrastructure-service-group/<UUID of your IS group>",
    "subtype": "generic",
    "href": "infrastructure-service-template/generic",
    "endpoint": "https://service.example.org:1234"
  }
}
'
Response: 
{
  "status" : 201,
  "message" : "infrastructure-service/a147218d-b331-411d-a0d2-b226b77617b4 created",
  "resource-id" : "infrastructure-service/a147218d-b331-411d-a0d2-b226b77617b4"
}

infrastructure-service-group

allowed:
POST
GET
DELETE
/api/infrastructure-service-group/uuid

The infrastructure-service-group resource is a logical container for your infrastructure-service and respective credential and data resources.

Examples

Create an infrastructure-service-group
POST
/api/infrastructure-service-group 

curl -XPOST https://nuvla.io/api/infrastructure-service-group -H 'content-type:application/json' -b cookies -d '''
{
    "description": "there are no mandatory attributes for this resource",
    "name": "My Group"
}
'''
Response: 
{
  "status" : 201,
  "message" : "infrastructure-service-group/2d40a72e-c6cd-4e6c-8904-e4d17ea0fc76 created",
  "resource-id" : "infrastructure-service-group/2d40a72e-c6cd-4e6c-8904-e4d17ea0fc76"
}

session

allowed:
POST
GET
DELETE
/api/session/uuid

The session resource allows you to use your credentials for authenticating with Nuvla.

NOTE: for later usage, we store the authenticated session in a file called cookies

Examples

Login with username and password
POST
/api/session 

curl -XPOST https://nuvla.io/api/session -H 'content-type:application/json' -c cookies -d '''
    {
      "template": {
        "href": "session-template/password",
        "username": "your_username",
        "password": "your_password"
      }
    }
'''
Response: 
{
  "status" : 201,
  "message" : "session/689df57a-b217-43eb-bf94-85a0ab638e2c created",
  "resource-id" : "session/689df57a-b217-43eb-bf94-85a0ab638e2c"
}
Login with API keys
POST
/api/session 

curl -XPOST https://nuvla.io/api/session -H 'content-type:application/json' -b cookies -d '''
    {
      "template": {
        "href": "session-template/api-key",
        "key": "credential/<apikey_uuid>",
        "secret": "<secret>"
      }
    }
'''
Response: 
{
  "status" : 201,
  "message" : "session/689df57a-b217-43eb-bf94-85a0ab638e2c created",
  "resource-id" : "session/689df57a-b217-43eb-bf94-85a0ab638e2c"
}

user

allowed:
POST
GET
PUT
DELETE
/api/user/uuid

The user resource allows you to create a new user account on Nuvla.

Examples

Create a user with an email and a password
POST
/api/user 

curl -XPOST https://nuvla.io/api/user -H 'content-type:application/json' -c cookies -d '
{
  "template": {
    "href": "user-template/email-password",
    "email": "your_email",
    "password": "your_password"
  }
}
'
Response: 
{
  "status" : 201,
  "message" : "user/689df57a-b217-43eb-bf94-85a0ab638e2c created",
  "resource-id" : "user/689df57a-b217-43eb-bf94-85a0ab638e2c"
}

Password must contain at least one uppercase character, one lowercase character, one digit, one special character, and at least 8 characters in total.

The creation of a user with email-password template does not require a session.

The user will receive an email with a callback that he have to follow to activate his account. After following the link, the state attribute of user document will transit from NEW to ACTIVE.

voucher

allowed:
POST
GET
PUT
DELETE
/api/voucher/uuid

The voucher resource let’s you create and manage digital vouchers, associated with any digital service provider, for better tracking and accounting of voucher consumption.

Examples

Create a new voucher
POST
/api/voucher 

curl -XPOST https://nuvla.io/api/voucher -H 'content-type:application/json' -b cookies -d '''
{
    "owner": "user/ef5cddf8-5d70-4c29-19ff-079ef7f90976",
    "supplier": "providerS",
    "target-audience": "researchers@institute.org",
    "amount": 50.0,
    "currency": "EUR",
    "code": "UnIqUeXYZ",
    "state": "NEW",
    "name": "My voucher",
    "description": "Description of my voucher",
    "service-info-url": "https://providerA/redeem-here",
    "wave": "wave 1",
    "batch": "batch_id_1234"
}
'''
Response: 
{
  "status" : 201,
  "message" : "voucher/932e3f49-d594-3eb7-b289-12f4988bcece created",
  "resource-id" : "voucher/932e3f49-d594-3eb7-b289-12f4988bcece"
}

Python API

(coming soon…)

Copyright 2021, SixSq