- REST API
- Python API
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¶m=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
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
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
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
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
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
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
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
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
The deployment
resource allows you to deploy an instance of a module
.
Examples
Start/Stop an application
# 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
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
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
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
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
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
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
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
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
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
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
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
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
The user
resource allows you to create a new user account on Nuvla.
Examples
Create a user with an email and a password
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
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
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…)