NAV
shell

SlipStream API Reference

Welcome to the SlipStream API. It has been designed to be comprehensive, covering all SlipStream resources, and portable, allowing access from any programming language. The API follows REST (Representational State Transfer) principles, was inspired from Richardson and Ruby’s excellent book RESTful Web Services, and reuses the standard and universally supported HTTP protocol.

SlipStream predates the standardization efforts for APIs and libraries within the cloud sector. Consequently, the original API is unique to SlipStream. However, as technologies have changed and the standards have emerged, the SlipStream developers have decided to incrementally adopt the Cloud Infrastructure Management Interface (CIMI) maintained by DMTF (https://www.dmtf.org). As a result, the full SlipStream API consists of two parts: a Legacy API and the CIMI API.

This documentation focuses on the low-level, HTTP-based REST API. Examples have been documented in Bash using curl; these examples are visible in the dark column on the right.

This API documentation page was created with Slate and is hosted by GitHub Pages. The sources are also hosted in GitHub, so feel free to report any snags in the GitHub repository.

Libraries

This documentation focuses on the low-level, HTTP-based REST API. As the HTTP protocol is supported by all programming languages, this API should be universally accessible. However, two language-specific SlipStream libraries are also maintained. These may be more appropriate if you are using Python or Clojure. The asynchronous part of the Clojure library is compatible with ClojureScript. See the table below for information on these libraries.

Language Sources Documentation
Python slipstream/SlipStreamPythonAPI Sphinx
Clojure(Script) slipstream/SlipStreamClojureAPI autodoc

For those people using Python, there is also a SlipStream plugin for Apache Libcloud available. The plugin is published in PyPi with separate documentation.

Legacy API

The legacy API follows REST principles where each resource corresponds to a URL and standard HTTP methods are used to manage those resources. In general, the resource URLs that identify collections follow the pattern:

https://nuv.la/<type>?query-param=value

and those identifying individual resources:

https://nuv.la/<type>/<id>?query-param=value

where the <type> corresponds to the resource type and <id>, to the resource identifier. Note that the resource identifier can have multiple components. In the case of modules, the last part of the resource identifier is a unique version number.

Resource Management (CRUD)

The standard HTTP methods are used to perform Search, Create, Read, Update, and Delete (SCRUD) operations on the resources. The mapping between the SCRUD actions and HTTP methods are shown in the following table. Details are provided in the description of each resource. Those resources without a CIMI notation follow the patterns of the legacy API.

Action HTTP Method URL
Search GET resource collection
Create POST resource collection
Read GET resource
Update PUT resource
Delete DELETE resource

Media Types

Adding ?media=xml(for XML) at the end of the URL in the browser, you request the response to be returned in the specified content-type, for example:

curl https://nuv.la/run?media=xml

is equivalent to

curl https://nuv.la/run -H "Content-Type: application/xml"

Generally, the legacy API accepts and returns documents in XML format. However, some resources can return HTML and/or JSON. You can control the media type of returned documents by adding an “accept” header to the HTTP request. Within a browser, the same can be done by adding a “media” query parameter. If the requested media type is not available, then XML will be returned instead.

Skeleton (new) Resources

curl https://nuv.la/module/examples/new?category=Image login -d username=<USER> -d password=<PASSWORD>

The above command returns a response body structured like this:

<imageModule category="Image" creation="2014-05-12 09:59:36.354 UTC" deleted="false" isBase="false" isLatestVersion="false" loginUser="" parentUri="module/Mebster" platform="" shortName="new" version="-1">
       <parameters>
               <entry>
                       <string>instanceid</string>
                       <parameter category="Output" description="Cloud instance id" isSet="false" mandatory="true" name="instanceid" order="0" order_="0" readonly="false" type="String"/>
               </entry>
               <entry>
                       <string>extra.disk.volatile</string>
                       <parameter category="Cloud" description="Volatile extra disk in GB" isSet="false" mandatory="true" name="extra.disk.volatile" order="0" order_="0" readonly="false" type="String"/>
               </entry>
               <entry>
                       <string>ec2-eu-west.instance.type</string>
                       <parameter category="ec2-eu-west" description="Cloud instance type" isSet="false" mandatory="true" name="ec2-eu-west.instance.type" order="0" order_="0" readonly="false" type="Enum">
                               <enumValues length="10">
                                       <string>m1.small</string>
                                       <string>m1.large</string>
                                       <string>m1.xlarge</string>
                                       <string>c1.medium</string>
                                       <string>c1.xlarge</string>
                                       <string>m2.xlarge</string>
                                       <string>m2.2xlarge</string>
                                       <string>m2.4xlarge</string>
                                       <string>cc1.4xlarge</string>
                                       <string>t1.micro</string>
                               </enumValues>
                       </parameter>
               </entry>
               <entry>
                       <string>exoscale-ch-gva.security.groups</string>
                       <parameter category="exoscale-ch-gva" description="Security Groups (comma separated list)" isSet="true" mandatory="true" name="exoscale-ch-gva.security.groups" order="0" order_="0" readonly="false" type="String">
                               <value>default</value>
                               <defaultValue>default</defaultValue>
                       </parameter>
               </entry>
               <entry>
                       <string>ec2-eu-west.security.group</string>
                       <parameter category="ec2-eu-west" description="Security groups (comma separated list)" isSet="true" mandatory="true" name="ec2-eu-west.security.group" order="0" order_="0" readonly="false" type="String">
                               <value>default</value>
                               <defaultValue>default</defaultValue>
                       </parameter>
               </entry>
               <entry>
                       <string>network</string>
                       <parameter category="Cloud" description="Network type" isSet="true" mandatory="true" name="network" order="0" order_="0" readonly="false" type="Enum">
                               <enumValues length="2">
                                       <string>Public</string>
                                       <string>Private</string>
                               </enumValues>
                               <value>Public</value>
                               <defaultValue>Public</defaultValue>
                       </parameter>
               </entry>
               <entry>
                       <string>exoscale-ch-gva.instance.type</string>
                       <parameter category="exoscale-ch-gva" description="Instance type (flavor)" isSet="false" mandatory="true" name="exoscale-ch-gva.instance.type" order="0" order_="0" readonly="false" type="String"/>
               </entry>
               <entry>
                       <string>hostname</string>
                       <parameter category="Output" description="hostname/ip of the image" isSet="false" mandatory="true" name="hostname" order="0" order_="0" readonly="false" type="String"/>
               </entry>
       </parameters>
       <authz groupCreateChildren="false" groupDelete="false" groupGet="false" groupPost="false" groupPut="false" inheritedGroupMembers="true" owner="meb" ownerCreateChildren="true" ownerDelete="true" ownerGet="true" ownerPost="true" ownerPut="true" publicCreateChildren="false" publicDelete="false" publicGet="false" publicPost="false" publicPut="false">
               <groupMembers />
       </authz>
       <cloudNames length="3">
               <string>exoscale-ch-gva</string>
               <string>ec2-eu-west</string>
               <string>default</string>
       </cloudNames>
       <runs/>
       <targets />
       <packages />
       <prerecipe/>
       <recipe/>
       <cloudImageIdentifiers />
</imageModule>

To retrieve example resource structures, especially for resource types that don’t yet exist, you can use the special new resource.

HTTP Request

GET https://nuv.la/<type>/new[?category=<category>]

Url Parameter

Parameter Required Description
type true Type of resource to retrieve (e.g. module, user)

Query Parameter

Parameter Required Description
category false Only required for module <type>. Can be: Project (default), Image or Deployment.

CIMI API

The Cloud Infrastructure Management Interface (CIMI) specification from DMTF describes a uniform, extensible, RESTful (HTTP) API for the management of cloud resources.

As CIMI’s underlying resource model closely resembles the existing SlipStream resource model and simplifies use of the API through standard patterns and autodiscovery, the SlipStream developers have decided to adopt this standard.

Autodiscovery

The CIMI API has been designed to allow for automatic discovery of the supported resources and management operations.

Resource Directory

# Cloud Entry Point (directory of resources)
curl https://nuv.la/api/cloud-entry-point
{
  "id" : "cloud-entry-point",
  "resourceURI" : "http://schemas.dmtf.org/cimi/2/CloudEntryPoint",
  "created" : "2016-06-21T17:31:14.950Z",
  "updated" : "2016-06-21T17:31:14.950Z",

  "baseURI" : "https://nuv.la/api/",

  "connectors" : {
    "href" : "connector"
  },
  "accountingRecords" : {
    "href" : "accounting-record"
  }, 

  "other fields" : "..."
}

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.

Operations

If the user is authorized to perform various management operations on a resource, the resource will contain an “operations” key. The value of the key will contain a list of actions (e.g. add, edit, delete, start) along with the URL to use to execute the action.

The HTTP methods to use for the CIMI add, edit, and delete operations are POST, PUT, and DELETE, respectively. All other operations use the HTTP POST method.

Resource Management (CRUD)

The CIMI standard defines patterns for all of the usual database actions: Search (or Query), Create, Read, Update, and Delete (SCRUD), although the specification uses “Add” for “Create” and “Edit” for “Update”.

See Section 4.2.1 of the CIMI specification for detailed descriptions of these patterns. Only differences from the standard patterns are documented here.

HTTP Methods

The following table shows the mapping between the resource management action and the HTTP method to be used. Those resources with a CIMI notation follow the CIMI patterns.

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

Add Pattern Variations

Note that there are two CIMI add (create) patterns:

In the Cloud Entry Point, any resource that has a corresponding template resource will use the templated add pattern. For example, the Session resource will use the templated add pattern because there is a SessionTemplate resource also listed.

Resource Selection

The CIMI specification provides advanced features for selecting resources when searching collections, including paging (CIMI Section 4.1.6.2), subsetting (4.1.6.3), sorting (4.1.6.6), and filtering (4.1.6.1).

All of the resource selection parameters are specified as HTTP query parameters. These are specified directly within the URL when using the HTTP GET method. They are specified in a body with the media type of application/x-www-form-urlencoded when using the PUT method. (Note that use of PUT for searches is an SlipStream extension to the CIMI standard.)

Ordering

The results can be ordered by the values of fields within the resources. The general form of a query with ordering is:

$orderby=attributeName[:asc|:desc], ...

The ascending (:asc, default) or descending (:desc) field is optional. The sorting is done using the natural order of the field values. Multiple $orderby parameters are allowed, in which case resources are sorted by the first attribute, then equal values are sorted by the second attribute, etc.

Paging

A range of resources can be obtained by setting the $first and $last (1-based) query parameters. The values default to the first and last resources, respectively, in the collection if explicit values are not provided.

Subsetting

Using the $select parameter allows you to select 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.

Multiple attributes may be specified by providing a string with comma-separated values or with multiple $select parameters.

Example select values

name,description

Filtering

Example filters

((alpha>2) and (beta>='bad value') or (nested/value!=false)
((property['alpha']="OK") or (missing=null))

The CIMI specification defines a simple, but powerful, filtering language to make sophisticated selections of resources. (See Section 4.1.6.1 of the full CIMI specification.) The syntax of the $filter query parameter consists of infix binary comparisons combined with and or or operators. Parentheses can be used to force the ordering of operations. Whitespace is ignored.

The following tables list the supported relational operators and types. All comparisons use the natural ordering of the data type.

operator description
= equal
!= not equal
< less than
<= less than or equal
> greater than
>= greater than or equal
^= starts with (SlipStream extension)
type comment
integer integer values
string single or double-quoted strings
date date in ISO8601 format
boolean either true or false
null null values (SlipStream extension)

The SlipStream filtering implementation is a superset of the CIMI filtering specification. These extentions include:

The filter syntax may be extended in the future to also support the “not” logical operation.

The full grammar of our extended CIMI filtering is documented in GitHub.

Aggregations

The SlipStream CIMI implementation also allows users to aggregate values over a set of filtered documents. This is useful for providing summary information concerning a set of documents, such as the sum of an attribute, average, etc.

The general form of a query with an aggregation is:

$aggregation=algorithm:attributeName, ...

Multiple aggregation expressions can be provided. The results of these calculations are provided in the “aggregations” section of the response. The supported aggregations are described in the following table.

algorithm description
min minimum value
max maximum value
sum sum of values
avg average of values
stats statistics of values
extendedstats extended statistics of values
count number of values/documents
percentiles binned percentiles of values
cardinality cardinality of a field
missing number of documents with missing field
terms histogram of values and counts

Deviations

SlipStream does not (yet) provide a complete implementation of the CIMI API and out of necessity deviates in several ways from the standard.

Media Types

The CIMI standard mandates the support of both XML and JSON. The SlipStream implementation only supports JSON (and in some cases URL-encoded forms).

Authorization

The CIMI standard does not mandate any authentication and authorization process. The schema of all resources in the SlipStream implementation includes an “acl” key. The Access Control List (ACL) of each resource describes who is authorized to manage that resource.

Searches

The CIMI standard only provides for searches over resource collections with the HTTP GET method. Because those filters can be quite long, there can be issues with the length of the GET URL. Consequently, SlipStream clients may also search resource collections using the HTTP PUT method with a body containing the filters (and other parameters) as a URL-encoded form.

Aggregations

As described earlier, SlipStream extends the CIMI standard to also include aggregating values over a collection of resources.

Authentication

Most SlipStream resources are only visible to authenticated users. The login process consists of creating a “session” resource via the standard CIMI templated add pattern and then using the returned token with subsequent interactions with the SlipStream server. The details are covered in the sections for the Session and SessionTemplate resources.

The supported Python and Clojure(Script) libraries (see Libraries) directly use the REST API defined here for Session management, but also provide higher-level functions that simplify the authentication process.

SessionTemplate (CIMI)

# List all of the configured authentication mechanisms
#
curl https://nuv.la/api/session-template
# You can get more details by using the "describe" action.
#
curl https://nuv.la/api/session-template/internal/describe
{
  "description" : {
    "displayName" : "Description",
    "category" : "common",
    "description" : "short, human-readable description",
    "type" : "string",
    "mandatory" : false,
    "readOnly" : false,
    "order" : 3
  },
  "properties" : {
    "displayName" : "Properties",
    "category" : "common",
    "description" : "user-defined properties",
    "type" : "map",
    "mandatory" : false,
    "readOnly" : false,
    "order" : 6
  },
  "group" : {
    "displayName" : "Authentication Group",
    "category" : "general",
    "description" : "optional label to group authentication methods",
    "type" : "string",
    "mandatory" : false,
    "readOnly" : false,
    "order" : 2
  },

  "more" : "values..."
}

SlipStream supports a wide variety of methods for authenticating with the server. The SessionTemplate resources represent the supported authentication methods for a given SlipStream server.

The SlipStream administrator defines the available methods by creating SessionTemplate resources on the server via the standard CIMI “add” pattern (and in most cases an associated Configuration resource). These can also be “edited” and “deleted” by the SlipStream administrator.

All users (including anonymous users) can list the SessionTemplates to discover supported authentication methods. These resources also support a “describe” action that provides a document with a detail description of authentication parameters.

One SessionTemplate that will always exist on the server is the “session-template/internal” resource. This allows logging into the server with a username and password pair stored in SlipStream’s internal database.

Session (CIMI)

An example document (named create-internal.json below) for authenticating via the “internal” (username and password) method.

{
  "sessionTemplate" : {
                        "href" : "session-template/internal",
                        "username" : "your-username",
                        "password" : "your-password"
                      }
}

A similar document for logging into with an API key/secret (named create-api-key.json). Verify the name of the template on the server; the administrator may have chosen a different name.

{
  "sessionTemplate" : {
                        "href" : "session-template/api-key",
                        "key" : "your-api-key",
                        "secret" : "your-api-secret"
                      }
}
# Be sure to get the URL from the cloud entry point!
# The cookie options allow for automatic management of the
# SlipStream authentication token (cookie).
curl https://nuv.la/api/session \
     -X POST \
     -H 'content-type: application/json' \
     -d @create-internal.json \
     --cookie-jar ~/cookies -b ~/cookies -sS

On a successful authentication, the above command will return a 201 (created) status, a “set-cookie” header, and a “location” header with the created session.

Users (clients) authenticate with the SlipStream server by referencing a SessionTemplate resource (to identify the authentication method), providing values for the associated parameters, and then creating a Session resource via the CIMI “add” pattern. A successful authentication attempt will return a token (as an HTTP cookie) that must be used in subsequent interactions with the SlipStream server.

The detailed process consists of the following steps:

  1. Browse the SessionTemplate resources to find the authentication method that you want to use. Unless you have a browser-based client, you will probably want to use either “internal” (username and password) or “api-key” (API key and secret). Use of API keys and secrets is preferred over the username and password.

  2. Prepare a “create” JSON document that references the SessionTemplate you have chosen and provides the corresponding parameters (e.g. username and password for “internal”).

  3. Post the “create” document to the Session collection URL. The correct URL can be determined from the CEP information.

  4. On a successful authentication request, a token will be returned allowing access to the SlipStream resources as the authenticated user. For convenience, this token is returned as an HTTP cookie.

The authentication token (cookie) must be used in all subsequent requests to the SlipStream server. The token (cookie) has a limited lifetime and you must re-authenticate with the server when the token expires.

Credential Template (CIMI)

# List all of the credential creation mechanisms
# NOTE: You must be authenticated.  Add the appropriate
# cookie options to the curl command.
#
curl https://nuv.la/api/credential-template
# You can get more details by using the "describe" action.
# NOTE: You must be authenticated.  Add the appropriate
# cookie options to the curl command.
#
curl https://nuv.la/api/credential-template/generate-api-key/describe

SlipStream must manage a variety of credentials to provide, for example, programmatic access to SlipStream or SSH access to virtual machines running on a cloud infrastructure. The CredentialTemplate resources correspond to the various methods that can be used to create these resources.

The parameters required can be found within each template, using the standard CIMI read pattern. Details for each parameter can be found by invoking the “describe” action on the resource.

Template Credential Description
import-ssh-public-key ssh-public-key imports an SSH public key from an existing key pair
generate-ssh-key-pair ssh-public-key generates a new SSH key pair, storing public key and returning private key
generate-api-key api-key generates API key and secret, storing secret digest and returning secret

Typically, there will also be Credential Template resources that describe the credentials for each supported cloud infrastructure.

Credential (CIMI)

SlipStream can manage credentials that are needed to access SlipStream or other services. Currently, SlipStream manages SSH public keys and API keys and secrets. Creating new Credential resources requires referencing a CredentialTemplate resource.

SSH Public Key

An example document (named create.json below) for creating a new SSH key pair.

{
  "credentialTemplate" : {
                           "href" : "credential-template/generate-ssh-key-pair"
                         }
}
# Be sure to get the URL from the cloud entry point!
# The cookie options allow for automatic management of the
# SlipStream authentication token (cookie).
curl https://nuv.la/api/credential \
     -X POST \
     -H 'content-type: application/json' \
     -d @create.json \
     --cookie-jar ~/cookies -b ~/cookies -sS

On a successful authentication, the above command will return a 201 (created) status, a “location” header with the created credential resource, and a JSON document containing the SSH private key of the generated key pair.

The “ssh-public-key” Credential resource stores the public key (in OpenSSH format), the algorithm used to create the key (“rsa” or “dsa”), and the fingerprint of the key itself. You can create any number of SSH public key credentials on the server.

These resources can be created either by providing the public key of an existing SSH key pair or by having the server generate a new SSH key pair. In the second case, the server will provide the private key in the 201 (created) response.

API Key and Secret

An example document (named create.json below) for creating an API key and secret with a lifetime of 1 day (86400 seconds).

{
  "credentialTemplate" : {
                           "href" : "credential-template/generate-api-key",
                           "ttl" : 86400
                         }
}
# Be sure to get the URL from the cloud entry point!
# The cookie options allow for automatic management of the
# SlipStream authentication token (cookie).
curl https://nuv.la/api/credential \
     -X POST \
     -H 'content-type: application/json' \
     -d @create.json \
     --cookie-jar ~/cookies -b ~/cookies -sS

On a successful authentication, the above command will return a 201 (created) status, a “location” header with the created credential resource, and a JSON document containing the plain text secret.

It is often useful to have credentials to log into the SlipStream server that are independent of your account credentials. This allows you, for example, to provide time-limited access or to revoke access at any time without affecting the access to your account with your main credentials.

For users who authenticate with external authentication mechanisms, an API key and secret is mandatory for programmic access to SlipStream, as the external authentication mechanisms usually cannot be used with the API.

The example shows how to create an API key and secret credential.

Service Catalog

The Service Catalog consists of several resources that allow users to view (and to select) the offers provided by the underlying cloud service providers. The SlipStream deployment process selects offers from the Service Catalog that match the resource requirements of a particular application, presents the alternatives to the users, and, after user selection, provisions the corresponding cloud resources.

Service Offer (CIMI)

An example service offer from the Open Telekom Cloud (OTC).

{
  "id" : "service-offer/0b2a46dd-f8c8-4420-a851-519daa581a1d",
  "name" : "(4/4096/800 c1.xlarge windows) [DE]",
  "description" : "VM (standard) with 4 vCPU, 4096 MiB RAM, 800 GiB root disk, windows [DE] (c1.xlarge)",
  "created" : "2017-06-26T11:13:42.883Z",
  "updated" : "2017-07-05T15:17:55.005Z",

  "connector" : {
    "href" : "open-telekom-de1"
  },

  "price:billingPeriodCode" : "MIN",
  "price:billingUnitCode" : "HUR",
  "price:currency" : "EUR",
  "price:freeUnits" : 0,
  "price:unitCost" : 0.38711111111111113,
  "price:unitCode" : "C62",

  "resource:class" : "standard",
  "resource:country" : "DE",
  "resource:diskType" : "SATA",
  "resource:instanceType" : "c1.xlarge",
  "resource:operatingSystem" : "windows",
  "resource:platform" : "openstack",
  "resource:ram" : 4096,
  "resource:vcpu" : 4,

  "otc:instanceType" : "c1.xlarge",
  "otc:flavorPurpose" : "Compute I Nr. 3",

  "acl" : {"..." : "..."}
}

Show all of the ServiceOffer resources from the “exoscale-ch-gva” cloud that provide more than 4096 MB of RAM. Be sure to escape the dollar sign in the $filter query parameter!

curl 'https://nuv.la/api/service-offer?$filter=connector/href="exoscale-ch-gva" and resource:ram>4096'

The ServiceOffer resource is the primary resource in the Service Catalog. Each offer describes a specific resource offer from a cloud service provider. The specific offer for a virtual machine would typically describe the offer’s CPU, RAM, and disk resources, the geographical location, and the price.

In the example offer from the Open Telekom Cloud (OTC), you can see three types of information: metadata (e.g. id, name), the cloud connector (in connector/href), and the cloud characteristics (e.g. price:unitCost, resource:country).

The schema for the cloud characteristics is open, allowing cloud providers to supply any information that is useful for users. The only requirement is that these attributes must be namespaced. The namespaces must be defined in a ServiceAttributeNamespace resources and the attribute itself may be described in a ServiceAttribute resource.

Currently, only SlipStream administrators can add, update, or delete ServiceOffer resources. The standard CIMI patterns for these actions apply to these resources. Most users will search the ServiceOffer entries by using a filter expression on the ServiceOffer collection. The example searches for all ServiceOffers from the “exoscale-ch-gva” cloud with more than 4096 MB of RAM.

Service Benchmark (CIMI)

An example service benchmark showing the Whetstone and Dhrystone benchmarks for an instance at Exoscale.


{
  "id": "service-benchmark/25de61b0-0a54-41ab-b8da-d2846194da13",
  "resourceURI": "http://sixsq.com/slipstream/1/ServiceBenchmark",
  "created": "2017-10-03T19:36:16.962Z",
  "updated": "2017-10-03T19:36:16.962Z",

  "credentials": [
    {
      "href": "credential/51f3ed99-c46e-43c8-9926-b8b64bcb86dd"
    }
  ],
  "serviceOffer": {
    "href": "service-offer/92fee6cb-86c2-4fff-be5e-c87e6b27cf37",
    "connector": {
      "href": "exoscale-ch-gva"
    },
    "resource:ram": 512,
    "resource:vcpu": 1,
    "resource:disk": 10,
    "resource:instanceType": "Micro"
  },

  "whetstone:score": 3997.3,
  "whetstone:units": "MWIPS",
  "whetstone:freetext": "Executed by a Nuvla App",

  "dhrystone:score": 33322937.2,
  "dhrystone:units": "lps",
  "dhrystone:freetext": "Executed by a Nuvla App",

  "acl" : {"..." : "..."},
  "operations": [ "..." ]
}

Show all of the ServiceBenchmark resources from the “exoscale-ch-gva”. With an average over the Whetstone score.

curl 'https://nuv.la/api/service-benchmark?$filter=serviceOffer/connector/href="exoscale-ch-gva"&$aggregation=avg:whetstone:score'
{
  "id" : "service-benchmark",
  "resourceURI" : "http://sixsq.com/slipstream/1/ServiceBenchmarkCollection",

  "count" : 25,
  "aggregations" : {
    "avg:whetstone:score" : {
      "value" : 4061.52400390625
    }
  },

  "serviceBenchmarks" : [ { "..." : "..." } ]
}

The ServiceBenchmark resource allows performance and other service metrics to be posted about one or more Service Offers. Such information can be used to make informed decisions about which cloud resources to provision for a particular application.

Like for the ServiceOffer, the schema is open, allowing publication of any benchmarks. The only requirement is that these attributes must be namespaced. The namespaces must be defined in a ServiceAttributeNamespace resources and the attribute itself may be described in a ServiceAttribute resource.

Service Attribute (CIMI)

Show all of the ServiceAttribute resources.

curl https://nuv.la/api/service-attribute

A ServiceAttribute resource provides semantic information concerning an attribute that appears in ServiceOffer resources. This resource is intended to provide information that helps humans understand the information provided in a ServiceOffer resource. The resource’s parameters are described in the table below.

Currently, only an administrator can create, update, or delete ServiceAttribute resources. These actions follow the standard CIMI patterns. Most users will only search these resources and look at the details for a particular ServiceAttribute resource.

Parameter Required Description
name true short human-readable tag
description true longer human-readable description
prefix true namespace prefix
attributeName true name of the attribute itself
type true type of the attribute’s value

Service Attribute Namespace (CIMI)

Search for all of the ServiceAttributeNamespace resources.

curl https://nuv.la/api/service-attribute-namespace

Show the ServiceAttributeNamespace resource for the “exoscale” prefix.

curl https://nuv.la/api/service-attribute-namespace/exoscale
{
  "id" : "service-attribute-namespace/exoscale",
  "resourceURI" : "http://sixsq.com/slipstream/1/ServiceAttributeNamespace",
  "created" : "2017-04-27T08:41:39.470Z",
  "updated" : "2017-04-27T08:41:39.470Z",

  "prefix" : "exoscale",
  "uri" : "http://sixsq.com/slipstream/schema/1/connector/exoscale",

  "acl" : {"..." : "..."}
}

Every attribute in a ServiceOffer resource must be namespaced to avoid collisions. The ServiceAttributeNamespace resources maintain the mapping between a namespace prefix and the associated, complete URI. The parameters are described in the table below.

A ServiceOffer resource cannot be uploaded to the server unless all of the namespace prefixes within the document have been defined.

Currently, only an administrator can create, update, or delete ServiceAttributeNamespace resources. These actions follow the standard CIMI patterns. Most users will only search these resources and look at the details for a particular ServiceAttributeNamespace resource.

Parameter Required Description
prefix true namespace prefix
uri true full URI associated with the prefix

Monitoring

VirtualMachine (CIMI)

These resources provide information for all active virtual machines on the underlying cloud infrastructures. Together they constitute the current global state of compute resources managed by SlipStream.

You must be authenticated with the SlipStream server to access the VirtualMachine collection and resources.

List Virtual Machines

curl https://nuv.la/api/virtual-machine -b ~/cookies -D -
HTTP/2 200
server: nginx
date: Wed, 17 Oct 2018 08:36:24 GMT
content-type: application/json
content-length: 3254718
vary: Accept-Encoding
strict-transport-security: max-age=31536000
{
  "resourceURI" : "http://sixsq.com/slipstream/1/VirtualMachineCollection",
  "id" : "virtual-machine",
  "count" : 870,

  ...

  "virtualMachines" : [ {
    "connector" : {
      "href" : "connector/exoscale-de-fra"
    },
    "ip" : "194.182.170.118",
    "credentials" : [ {
      "href" : "credential/7353af45-cd25-4bb0-9444-ee1935aa8a81"
    } ],
    "updated" : "2018-10-17T08:28:59.345Z",
    "billable" : true,
    "created" : "2018-10-15T13:54:48.539Z",
    "state" : "running",
    "currency" : "EUR",
    "instanceID" : "0781484e-c82a-4522-b339-386e12c9e8ce",
    "id" : "virtual-machine/a5d482e1-1fc0-33b7-b3b0-78fc4a5d08b2",
    ...    
    }]
    ...

Listing the VirtualMachine resources follows the standard CIMI pattern, using an HTTP GET request on the collection URL.

The example command returns the HTTP headers of the request and then the full list of Virtual Machine resources as a JSON document. The returned JSON document contains some general information concerning, for example, the total number of documents (“count” key), followed by the list of VirtualMachine resource under the “virtualMachines” key.

Filtering Virtual Machines

The full CIMI filtering syntax (with SlipStream extensions) can be used to find a subset of the VirtualMachine resources. For example, the filter terms:

would limit the response to only virtual machines in a running state on the “exoscale-de-fra” cloud. Other query parameters, can also be used, for example $last=0 to just return the global count information.

curl 'https://nuv.la/api/virtual-machine?$filter=connector/href="connector/exoscale-de-fra"%20and%20state="running"&$last=0' -b ~/cookies -D -
{
  "count" : 351,
  "acl" : {
    "owner" : {
      "principal" : "ADMIN",
      "type" : "ROLE"
    },
    "rules" : [ {
      "principal" : "ADMIN",
      "type" : "ROLE",
      "right" : "MODIFY"
    }, {
      "principal" : "USER",
      "type" : "ROLE",
      "right" : "VIEW"
    } ]
  },
  "resourceURI" : "http://sixsq.com/slipstream/1/VirtualMachineCollection",
  "id" : "virtual-machine",
  "operations" : [ {
    "rel" : "add",
    "href" : "virtual-machine"
  } ],
  "virtualMachines" : [ ]
}

StorageBucket (CIMI)

These resources provide information for S3 buckets accessible via the cloud credentials stored in SlipStream. Together they provide a global snapshot of S3 object storage on the cloud infrastructures accessible through SlipStream.

You must be authenticated with the SlipStream server to access the StorageBucket collection and resources.

List and Filter Storage Buckets

Listing and filtering the StorageBucket resources follows the standard CIMI patterns. The full CIMI filtering syntax is available when listing the StorageBucket resources.

curl 'https://nuv.la/api/storage-bucket?$last=1' -b ~/cookies -D -
{
  "count" : 638,
  "acl" : {
    "owner" : {
      "principal" : "ADMIN",
      "type" : "ROLE"
    },
    "rules" : [ {
      "principal" : "ADMIN",
      "type" : "ROLE",
      "right" : "MODIFY"
    }, {
      "principal" : "USER",
      "type" : "ROLE",
      "right" : "VIEW"
    } ]
  },
  "resourceURI" : "http://sixsq.com/slipstream/1/StorageBucketCollection",
  "id" : "storage-bucket",
  "operations" : [ {
    "rel" : "add",
    "href" : "storage-bucket"
  } ],
  "storageBuckets" : [ {
    "connector" : {
      "href" : "connector/exoscale-ch-gva"
    },
    "description" : "obj store usage for bucket slipstream-test-1533528220, from credential credential/df3e1df6-37e5-4bf2-9366-7f0d5ae072a8 in connector/exoscale-ch-gva",
    "credentials" : [ {
      "href" : "credential/df3e1df6-37e5-4bf2-9366-7f0d5ae072a8"
    } ],
    "updated" : "2018-08-22T19:06:51.545Z",
    "name" : "bucket slipstream-test-1533528220 size in connector/exoscale-ch-gva",
    "created" : "2018-08-22T15:09:25.951Z",
    "usageInKiB" : 51,
    "currency" : "EUR",
    "id" : "storage-bucket/a048beb7-2dc2-3899-92fc-2f6abeadd1f5",
    "acl" : {
      "owner" : {
        "type" : "ROLE",
        "principal" : "ADMIN"
      },
      "rules" : [ {
        "principal" : "SixSq:/admin",
        "right" : "VIEW",
        "type" : "ROLE"
      }, {
        "principal" : "ADMIN",
        "right" : "ALL",
        "type" : "ROLE"
      }, {
        "principal" : "RHEA:/admin",
        "right" : "VIEW",
        "type" : "ROLE"
      }, {
        "principal" : "ADMIN",
        "right" : "VIEW",
        "type" : "ROLE"
      } ]
    },
    "operations" : [ {
      "rel" : "edit",
      "href" : "storage-bucket/a048beb7-2dc2-3899-92fc-2f6abeadd1f5"
    }, {
      "rel" : "delete",
      "href" : "storage-bucket/a048beb7-2dc2-3899-92fc-2f6abeadd1f5"
    } ],
    "bucketName" : "slipstream-test-1533528220",
    "resourceURI" : "http://sixsq.com/slipstream/1/StorageBucket",
    "serviceOffer" : {
      "resource:host" : "sos.exo.io",
      "href" : "service-offer/08b86233-0ef2-4716-a58d-901816738955",
      "price:unitCost" : 2.0E-5,
      "resource:storage" : 1,
      "resource:type" : "DATA",
      "resource:platform" : "S3",
      "price:billingUnit" : "GiBh",
      "price:currency" : "EUR"
    }
  } ]
}

Quota (CIMI)

The collection of Quota resources defines the overall resource utilization policy for the SlipStream server. Each Quota resource defines a limit on an identified resource. For new resource requests, SlipStream will verify that the request will not exceed the defined quotas before executing the request. Currently, SlipStream only checks quotas when deploying new workloads.

The Quota resource follows the standard CIMI SCRUD patterns. It is not a templated resource and uses the simple CIMI add pattern.

Quota Attributes

An abbreviated example of a Quota resource that sets a limit (116) on the total number (count:id) of VirtualMachine resources for the given credential for the MYORG organization.

{
  "id": "quota/a6d547cd-3855-4b24-aae2-73ad0707d828",
  "resourceURI": "http://sixsq.com/slipstream/1/Quota",

  "name": "max_instances in connector/exoscale-ch-dk",
  "description": "limits regarding max_instances, for credential credential/45765716-33f0-46bb-b3de-7bef04a58998 in connector/exoscale-ch-dk",

  "updated": "2018-10-18T05:17:21.162Z",
  "created": "2018-08-06T05:30:03.214Z",

  "resource": "VirtualMachine",
  "selection": "credentials/href='credential/45765716-33f0-46bb-b3de-7bef04a58998'"
  "aggregation": "count:id",

  "limit": 116,

  "acl": {
    "owner": {
      "type": "ROLE",
      "principal": "ADMIN"
    },
    "rules": [
      {
        "right": "VIEW",
        "type": "ROLE",
        "principal": "MYORG:can_deploy"
      }
    ]
  },
  "operations": [
    {
      "rel": "http://sixsq.com/slipstream/1/action/collect",
      "href": "quota/a6d547cd-3855-4b24-aae2-73ad0707d828/collect"
    }
  ]
}
Attribute        Description
resource Identifies the resource to which the quota applies. Current examples include “VirtualMachine” and “NuvlaBoxRecord”, the source of the current debate.
selection A CIMI filter expression that identifies the resources to include in the calculation of the current resource utilization.
aggregation A CIMI aggregation expression that calculates the values for the current resource utilization. One number is calculated with the access rights of the user and another, with the access rights of “super”.
limit The value to compare the calculated resource utilization against.
acl Defines to whom a given quota resource applies. If a quota resource is visible to an entity (user, group, role, etc.), it applies to that entity.

Collect Action

The “collect” action (shown in the operations section) can be executed by sending an HTTP POST request to the given URL.

This action will calculate the Quota’s aggregation by running the defined selection filter against the specified resource collection. This will be done twice: once as the user and once with as the administrator.

The Quota resource will be returned with two attributes added: current and currentAll. These are described below.

current Aggregation result when run as the user.
currentAll Aggregation result when run as the administrator.

The enforcement algorithm for the resource will then accept or reject a request by comparing the current or currentAll values to the defined limit. How the comparison is done and how multiple quotas are combined are defined by the enforcement algorithm itself.

Metering (CIMI)

The Metering resources are snapshots of the monitoring information (VirtualMachine and StorageBucket resources) that are taken every minute to provide historical usage information. These resources can be queried to provide aggregate usage information for a given time period, specific groups or users, etc.

Filtering and Aggregation

Provide the average number of CPU cores and total cost for the “user/test” user for the given time period.

curl 'https://nuv.la/api/metering?$last=0&deployment/user!='user/test'&$aggregation=sum:price,avg:serviceOffer/resource:vpu&$filter=created<"now"%20and%20created>"2018-09-13T00:00:00Z"%20and%20deployment/user/href="user/test"' \
    -b ~/cookies -D -
{
  "count" : 45083692,
  "aggregations" : {
    "avg:serviceOffer/resource:vcpu" : {
      "value" : 6.730052249501845
    },
    "sum:price" : {
      "value" : 187186.03962752942
    }
  },
  "acl" : {
    "owner" : {
      "principal" : "ADMIN",
      "type" : "ROLE"
    },
    "rules" : [ {
      "principal" : "ADMIN",
      "type" : "ROLE",
      "right" : "MODIFY"
    }, {
      "principal" : "USER",
      "type" : "ROLE",
      "right" : "VIEW"
    } ]
  },
  "resourceURI" : "http://sixsq.com/slipstream/1/MeteringCollection",
  "id" : "metering",
  "operations" : [ {
    "rel" : "add",
    "href" : "metering"
  } ],
  "meterings" : [ ]
}

Typically you will query these resources by providing a time window, a user/group, and the value(s) to aggregate. To filter by the date and user, a $filter expression similar to the following can be used:

created<"now-1d" and created>"2018-09-13T00:00:00Z"

Explicit dates can be used or relative times compared to “now”. The support for “now” expressions is an extension to the CIMI standard. The “now” expression syntax comes directly from the underlying Elasticsearch database.

You will almost never be interested in the individual metering resources. As there are an extremely large number in any time window, the list can be suppressed by providing the query parameter $last=0. With the general information and any aggregation information will be returned, but none of the selected resources.

You can review the aggregation documentation to see what aggregations are supported. In the context of accounting, the “count”, “avg”, and “sum” aggregations are usually the most useful. To sum the money spent on the resources (assuming that prices have been defined for the cloud), you can use a query expression like the following:

$aggregation=sum:price

to calculate the total cost of the selected resources. Multiple aggregations can be specified either as a multiple parameters or as a comma-separated value. The requested information will be returned in the “aggregations” key of the response.

The example shows a full example and the JSON response.

User

User (CIMI)

User resources contain personal information and a few parameters concerning the registered users. This is a templated resource, so creating a new user requires a template. All the SCRUD actions follow the standard CIMI patterns.

UserTemplate (CIMI)

Listing of the available UserTemplate resources on Nuvla.

curl 'https://nuv.la/api/user-template?$select=name,description'
{
  "count" : 15,
  ...
  "resourceURI" : "http://sixsq.com/slipstream/1/UserTemplateCollection",
  "id" : "user-template",
  "userTemplates" : [ {
    "name" : "ESRF Realm",
    "description" : "Creates a new user through OIDC registration",
    ...
    },
    "resourceURI" : "http://sixsq.com/slipstream/1/UserTemplate",
    "operations" : [ {
      "rel" : "http://sixsq.com/slipstream/1/action/describe",
      "href" : "/describe"
    } ]
  }, {
    "name" : "INFN Realm",
    "description" : "Creates a new user through OIDC registration",
    ...

UserTemplate resources define the “user registration” methods that are permitted by the server. The UserTemplate collection follows all of the CIMI SCRUD patterns.

The server will always contain the “direct” user template. This template is only acceptable to administrators and allows the direct creation of a new user without any email verification, etc.

The system administrator may create additional templates to allow other user registration methods. If the ACL of the template allows for “anonymous” access, then the server will support self-registration of users. The registration processes will typically require additional validation step, such as email verification.

UserParam (CIMI)

The UserParam resource contains default values for a number of user-level parameters. These include things like the default deployment timeout, verbosity, and the default cloud service.

This is a templated resource that follows all the standard CIMI SCRUD patterns. Normally, these resources are created during the user registration process and not created manually.

A UserParam resource can be matched to the User resource via a $filter like the following:

acl/owner/principal='83c39a85-1d03-4931-9c82-c015e0452359'

where the value is the id of the User resource without the “user/” prefix.

UserParamTemplate (CIMI)

The UserParamTemplate resources allow UserParam resources to be created. Normally, users and administrators will never create a UserParam resource manually and will not need to use these templates.

UserIdentifier (CIMI)

The UserIdentifier resources provide a mapping between an external identity (for a given authentication method) and a registered user. Multiple external identities can be mapped to the same SlipStream user, allowing that user to authenticate in different ways while using the same account.

This resource follows the standard CIMI SCRUD patterns. However, the resource id is a hashed value of the identifier. This guarantees that a single external identifier cannot be mapped to more than one user.

Users will normally not be concerned with these resources, although they can list them to see what authentication methods are mapped to their accounts.

Administrators may create new UserIdentifier resources to allow a user to have more than one authentication method.

Applications

Module (Legacy)

(Extracted from the tutorial documentation)

Metadata about your images and deployments are organized into projects in SlipStream. Each project consists of a number of modules. The modules may be Project, Machine Image or Deployment modules:

These items are normalised into module resources in the REST API.

Get a module

curl https://nuv.la/module/<module> --user <user>:<password> -H "Content-Type: application/xml"

The above command returns a response body structured like this:

<imageModule category="Image" creation="2013-12-02 17:00:37.421 UTC" deleted="false" description="Minimal installation of the Ubuntu 12.04 (LTS) operating system." imageId="8c7e60ae-3a30-4031-a3e6-29832d85d7cb" isBase="true" isLatestVersion="true" lastModified="2014-05-04 12:36:06.105 UTC" loginUser="ubuntu" logoLink="http://design.ubuntu.com/wp-content/uploads/ubuntu-logo14.png" parentUri="module/examples/images" platform="ubuntu" shortName="ubuntu-12.04" version="480">
    <parameters>
        <entry>
            <string>extra.disk.volatile</string>
            <parameter category="Cloud" description="Volatile extra disk in GB" isSet="false" mandatory="true" name="extra.disk.volatile" order="0" order_="0" readonly="false" type="String"/>
        </entry>
        <entry>
            <string>exoscale-ch-gva.instance.type</string>
            <parameter category="exoscale-ch-gva" description="Instance type (flavor)" isSet="true" mandatory="true" name="exoscale-ch-gva.instance.type" order="0" order_="0" readonly="false" type="String">
                <value>Small</value>
                <defaultValue>Small</defaultValue>
            </parameter>
        </entry>
...
        <entry>
            <string>ec2-eu-west.security.group</string>
            <parameter category="ec2-eu-west" description="Security groups (comma separated list)" isSet="true" mandatory="true" name="ec2-eu-west.security.group" order="0" order_="0" readonly="false" type="String">
                <value>default</value>
                <defaultValue>default</defaultValue>
            </parameter>
        </entry>
    </parameters>
    <authz groupCreateChildren="false" groupDelete="false" groupGet="true" groupPost="true" groupPut="false" inheritedGroupMembers="true" owner="sixsq" ownerCreateChildren="true" ownerDelete="true" ownerGet="true" ownerPost="true" ownerPut="true" publicCreateChildren="false" publicDelete="false" publicGet="true" publicPost="true" publicPut="false">
        <groupMembers />
    </authz>
    <commit author="sixsq"/>
    <published publicationDate="2014-05-04 12:36:06.105 UTC"/>
    <cloudNames length="3">
        <string>exoscale-ch-gva</string>
        <string>ec2-eu-west</string>
        <string>default</string>
    </cloudNames>
    <runs/>
    <targets />
    <packages />
    <prerecipe/>
    <recipe/>
    <cloudImageIdentifiers>
        <cloudImageIdentifier cloudImageIdentifier="ami-a0dd3dd7" cloudServiceName="ec2-eu-west"/>
        <cloudImageIdentifier cloudImageIdentifier="8c7e60ae-3a30-4031-a3e6-29832d85d7cb" cloudServiceName="exoscale-ch-gva"/>
    </cloudImageIdentifiers>
</imageModule>
curl https://nuv.la/module/examples/foo -H "Content-Type: application/xml" --user <user>:<password> > foo.xml

Get a module (i.e. image, deployment or project).

HTTP Request

GET https://nuv.la/module/<module>[/<version>]

URL Parameters

Parameter Required Description
module true Unique identifier of the module - e.g. examples/images/ubuntu-12.04.
version false Version of the module to update. If not provided, get the latest (most recent)

Update a module

curl https://nuv.la/module/<module> --user <user>:<password> --data @<file> -X PUT -H "Content-Type: application/xml"

where <file> is an xml file - e.g. the result of a previous GET on the same resource

The above command returns a header structured like this:

HTTP/1.1 200 OK
Date: Mon, 12 May 2014 15:16:49 GMT
Accept-Ranges: bytes
Location: https://nuv.la/module/examples/foo/1199
Server: Restlet-Framework/2.1m4
Set-Cookie: com.sixsq.slipstream.cookie=com.sixsq.idtype=local&com.sixsq.identifier=test&com.sixsq.expirydate=1399951006191&com.sixsq.signature=-cotcj9t5rzu3zx2uof96x8scptxh5mbraazmf63doem22tkvlq1519twaz7uxlvtyyxd0fxvygvrsn1hip09yvn7v11c9a74j21; Path=/
Content-Length: 0

To see the header, add -D - (with the trailing dash) to the curl command

Update a module (i.e. image, deployment or project).

The PUT request will create a new resource with the same <module> name but a higher <version>. The response includes the new fully qualified resource.

HTTP Request

PUT https://nuv.la/module/<module>[/<version>]

The Location attribute in the response header provides the full url of the updated resource, with the incremented version.

URL Parameters

Parameter Required Description
module true Unique identifier of the module - e.g. examples/images/ubuntu-12.04. If not provided, list the root modules.
version false Version of the module. If not provided, get the latest (most recent)

Delete a module

curl https://nuv.la/module/<module> -u <user>:<password> -X DELETE -D -

The above command returns a header structured like this:

HTTP/1.1 204 No Content
Date: Tue, 13 May 2014 03:08:15 GMT
Accept-Ranges: bytes
Location: https://nuv.la/module/examples/toto/11
Server: Restlet-Framework/2.1m4
Set-Cookie: com.sixsq.slipstream.cookie=com.sixsq.idtype=local&com.sixsq.identifier=test&com.sixsq.expirydate=1399993694970&com.sixsq.signature=izoalqmos489wxw8z25k03nqtsdfyxyv2ak5adi1e0h73zdziq45y1eat66tcob5ybvh7oe5gbh8es1onj4f6orj2enrqu9w9j0; Path=/
Content-Length: 0

Delete a module (i.e. image, deployment or project).

The DELETE request will delete the specified resource if fully qualified (i.e. including the <VERSION>) or the latest version otherwise.

HTTP Request

DELETE https://nuv.la/module/<module>[/<version>]

URL Parameters

Parameter Required Description
module true Unique identifier of the module - e.g. examples/images/ubuntu-12.04.
version false Version of the module. If not provided, delete the latest (most recent)

Delete all versions of a module

curl https://nuv.la/module/<module>/ -u <user>:<password> -X DELETE -D -

The above command returns a header structured like this:

HTTP/1.1 204 No Content
Date: Tue, 13 May 2014 03:08:15 GMT
Accept-Ranges: bytes
Location: https://nuv.la/module/examples/toto/11
Server: Restlet-Framework/2.1m4
Set-Cookie: com.sixsq.slipstream.cookie=com.sixsq.idtype=local&com.sixsq.identifier=test&com.sixsq.expirydate=1399993694970&com.sixsq.signature=izoalqmos489wxw8z25k03nqtsdfyxyv2ak5adi1e0h73zdziq45y1eat66tcob5ybvh7oe5gbh8es1onj4f6orj2enrqu9w9j0; Path=/
Content-Length: 0

Delete all versions of a module (i.e. image, deployment or project) for which the authenticated user has the “delete” right.

The DELETE request will delete all versions of the specified resource.

HTTP Request

DELETE https://nuv.la/module/<module>/

URL Parameters

Parameter Required Description
module true Unique identifier of the module with the trailing slash - e.g. examples/images/ubuntu-12.04/.

Module history (versions)

curl https://nuv.la/module/<module>/ -u <user>:<password>
<versionList>
   <item resourceUri="module/examples/an-image/12" lastModified="2014-05-13 04:53:47.339 CEST" version="12" category="Image" name="an-image">
      <authz owner="test" ownerGet="true" ownerPut="true" ownerPost="true" ownerDelete="true" ownerCreateChildren="true" groupGet="false" groupPut="false" groupPost="false" groupDelete="false" groupCreateChildren="false" publicGet="false" publicPut="false" publicPost="false" publicDelete="false" publicCreateChildren="false" inheritedGroupMembers="true">
         <groupMembers />
      </authz>
      <commit author="test">
         <comment></comment>
      </commit>
   </item>
   <item resourceUri="module/examples/an-image/2" lastModified="2014-05-12 14:33:53.39 CEST" version="2" category="Image" name="an-image">
      <authz owner="test" ownerGet="true" ownerPut="true" ownerPost="true" ownerDelete="true" ownerCreateChildren="true" groupGet="false" groupPut="false" groupPost="false" groupDelete="false" groupCreateChildren="false" publicGet="false" publicPut="false" publicPost="false" publicDelete="false" publicCreateChildren="false" inheritedGroupMembers="true">
         <groupMembers />
      </authz>
      <commit author="test"/>
   </item>
</versionList>

List all the history (i.e. all the versions) of the module. Since each PUT creates a new version of the module, this request allows users to list these.

HTTP Request

GET https://nuv.la/module/<module>/

URL Parameters

Parameter Required Description
module true Unique identifier of the module with the trailing slash - e.g. examples/images/ubuntu-12.04.

Module (CIMI)

This is a prototype resource that will eventually replace the legacy module resource. This resource should not be used in production.

ModuleApplication (CIMI)

This is a prototype resource that supports the new CIMI Module resource. This resource would be accessed only through the CIMI Module resource and not used directly. This should not be used in production at this time.

ModuleComponent (CIMI)

This is a prototype resource that supports the new CIMI Module resource. This resource would be accessed only through the CIMI Module resource and not used directly. This should not be used in production at this time.

ModuleProject (CIMI)

This is a prototype resource that supports the new CIMI Module resource. This resource would be accessed only through the CIMI Module resource and not used directly. This should not be used in production at this time.

Deployment

Run (Legacy)

The run resource represents an execution in the cloud - i.e. running VMs. SlipStream supports 3 types of runs:

The run resource therefore represents one or several VMs, running or not depending on the state of the run.

List all Runs

curl https://nuv.la/run -u <user>:<password>
<runs offset="0" limit="20" count="20" totalCount="93">
   <item resourceUri="run/fed1dd04-aa05-4a92-abb8-ed279f1f4dd4" uuid="fed1dd04-aa05-4a92-abb8-ed279f1f4dd4" moduleResourceUri="module/SlipStream/deploy-slipstream-dpl/745" status="Done" abort="" startTime="2015-03-17 13:34:51.440 UTC" cloudServiceNames="exoscale-ch-gva" username="sixsq_dev" type="Orchestration" tags=""/>
   <item resourceUri="run/1ab29b6a-f08c-45ae-9cf4-336a0415f46c" uuid="1ab29b6a-f08c-45ae-9cf4-336a0415f46c" moduleResourceUri="module/SlipStream/deploy-slipstream-dpl/742" status="Cancelled" abort="Failed running &apos;execute&apos; target on &apos;slipstream.1&apos;" startTime="2015-03-17 10:52:05.331 UTC" cloudServiceNames="exoscale-ch-gva" username="sixsq_dev" type="Orchestration" tags=""/>
   ...
</runs>

List all runs of a user.

HTTP Request

GET https://nuv.la/run

Get a Run

curl https://nuv.la/run/<run> -u <user>:<password>
<runs>
   <item resourceUri="run/4f187379-cdb9-470d-9656-b6fac6dc33d8" uuid="4f187379-cdb9-470d-9656-b6fac6dc33d8" moduleResourceUri="module/examples/tutorials/service-testing/system/471" status="Done" startTime="2014-05-10 15:22:56.882 UTC" cloudServiceName="exoscale-ch-gva" username="meb" type="Orchestration" tags=""/>
   <item resourceUri="run/fa3b9652-9dac-49e2-9573-b761777c8238" uuid="fa3b9652-9dac-49e2-9573-b761777c8238" moduleResourceUri="module/examples/tutorials/service-testing/system/471" status="Done" startTime="2014-05-10 15:13:29.352 UTC" cloudServiceName="exoscale-ch-gva" username="meb" type="Orchestration" tags=""/>
</runs>

Get a specific run.

HTTP Request

GET https://nuv.la/run/<run-uuid>

URL Parameters

Parameter Required Description
run-uuid true Run unique identifier - e.g. fa3b9652-9dac-49e2-9573-b761777c8238.

Create a Run

curl https://nuv.la/run -d refqname=module/examples/an-image -d type=Run -u <user>:<password> -X POST -H "Content-Type: text/plain" -D -

The above command returns a header structured like this:

HTTP/1.1 201 Created
Date: Tue, 13 May 2014 11:29:56 GMT
Accept-Ranges: bytes
Location: https://nuv.la/run/cce5ac6d-5465-4773-9875-66f21c65e15e
Server: Restlet-Framework/2.1m4
Set-Cookie: com.sixsq.slipstream.cookie=com.sixsq.idtype=local&com.sixsq.identifier=test&com.sixsq.expirydate=1400023769837&com.sixsq.signature=eck79w5qyslb16ke31vfof2b9o6729mcsjgnsqc143nsgqkuepmkgqnaakv544x7nankz4875p0uyg8unl8d5m4dl60wzr6pcpn; Path=/
Content-Length: 0

Create a new standard (non-scalable) run.

The Location attribute in the response header provides the full url of the updated resource, with the incremented version.

HTTP Request

POST https://nuv.la/run

Body Parameters

Parameter Required Description
refqname true Reference module from which to create a run. Must be an Image or Deployment category - e.g. module/SlipStream/deploy-slipstream-dpl.
type depends Type of run. This is only required when running an image, since we can either deploy a VM (i.e. simple run) or create a new image (i.e. build). See below for run type definition.
Run Type Description
Orchestration Deployment: only applies to deployment category. This is the only valid type value for deployment, thus does not have to be provided.
Machine Build: build a new image on the targeted cloud and set the unique id back in the image definition.
Run Simple run: single VM deployment.

Create a scalable Run

curl https://nuv.la/run -d refqname=module/examples/a-deployment -d mutable=true -u <user>:<password> -X POST -H "Content-Type: text/plain" -D -

The above command returns a header structured like this:

HTTP/1.1 201 Created
Date: Tue, 13 May 2014 11:29:56 GMT
Accept-Ranges: bytes
Location: https://nuv.la/run/cce5ac6d-5465-4773-9875-66f21c65e15e
Server: Restlet-Framework/2.1m4
Set-Cookie: com.sixsq.slipstream.cookie=com.sixsq.idtype=local&com.sixsq.identifier=test&com.sixsq.expirydate=1400023769837&com.sixsq.signature=eck79w5qyslb16ke31vfof2b9o6729mcsjgnsqc143nsgqkuepmkgqnaakv544x7nankz4875p0uyg8unl8d5m4dl60wzr6pcpn; Path=/
Content-Length: 0

Create a new scalable run from a predefined deployment.

The Location attribute in the response header provides the full url of the newly created run.

HTTP Request

POST https://nuv.la/run

Body Parameters

Parameter Required Description
refqname true Reference module from which to create a run. Must be a Deployment category - e.g. module/SlipStream/deploy-slipstream-dpl.
mutable true Define that the run is scalable - i.e., providing a possibility to add and remove node instances.

Add node instances to a scalable Run

curl https://nuv.la/run/cce5ac6d-5465-4773-9875-66f21c65e15e/centos_node -d n=2 -u <user>:<password> -X POST -H "Content-Type: text/plain" -D -

The above command requests addition of two instances of the node type centos_node, returns 201 and the list of the created node instances in the body

HTTP/1.1 201 Created
Content-type: text/plain; charset=UTF-8
Content-length: 27
Server: Restlet-Framework/2.2.1
Accept-ranges: bytes
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
Date: Wed, 25 Jun 2014 21:49:19 GMT
Set-cookie: com.sixsq.slipstream.cookie=com.sixsq.idtype=local&com.sixsq.identifier=test&com.sixsq.expirydate=1403776159248&com.sixsq.signature=k82fu5qecds8f4grtvxjxkv698sdr3bw6wtieqrsanjnqjqg9eb6imoq217ww0stu9q23gi8y8y4rcovn7sse1ah65881j7k3hw; Path=/

centos_node.2,centos_node.3

Add node instances on a scalable Run.

HTTP Request

POST https://nuv.la/run/<run-uuid>/<node-name>

URL Parameters

Parameter Required Description
run-uuid true Run unique identifier - e.g. fa3b9652-9dac-49e2-9573-b761777c8238.
node-name true Node name - e.g. centos_node.

Body Parameters

Parameter Required Description
n false Defines a number of node instances to be added. If omitted, one node instance is added.

Remove node instances from a Run

curl https://nuv.la/run/cce5ac6d-5465-4773-9875-66f21c65e15e/centos_node -d ids=1,2 -u <user>:<password> -X DELETE -D -

The above command requests deletion of two instances with indices 1 and 2 of the node type centos_node and returns 204 on success.

HTTP/1.1 204 No Content
Content-length: 0
Server: Restlet-Framework/2.2.1
Accept-ranges: bytes
Date: Tue, 24 Jun 2014 14:09:01 GMT
Set-cookie: com.sixsq.slipstream.cookie=com.sixsq.idtype=local&com.sixsq.identifier=test&com.sixsq.expirydate=1403662141504&com.sixsq.signature=atvt4x3mc5p0b8komk26olefqeu392m9m63sb44t7k0t86rk2lw0n15o27al7ijm4opqhavh84fmqiti5xnewpldh3skm0rsuwq; Path=/

Remove node instances from a Run.

HTTP Request

DELETE https://nuv.la/run/<run-uuid>/<node-name>

URL Parameters

Parameter Required Description
run-uuid true Run unique identifier - e.g. fa3b9652-9dac-49e2-9573-b761777c8238.
node-name true Node name - e.g. centos_node.

Body Parameters

Parameter Required Description
ids true Defines the comma separated list of indices of the node instances to be removed.

Get instance names of a node in Run

curl https://nuv.la/run/cce5ac6d-5465-4773-9875-66f21c65e15e/centos_node -u <user>:<password> "Content-Type: text/plain" -D -

The above command requests a list of the instance names of the node centos_node. On success, the return code is 200 and the body contains the comma separated list of the instance names.

HTTP/1.1 200 OK
Content-type: text/plain; charset=UTF-8
Content-length: 65
Server: Restlet-Framework/2.2.1
Accept-ranges: bytes
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
Date: Wed, 25 Jun 2014 21:57:21 GMT
Set-cookie: com.sixsq.slipstream.cookie=com.sixsq.idtype=local&com.sixsq.identifier=test&com.sixsq.expirydate=1403776630991&com.sixsq.signature=-gkbwu2gknk54fcfbg5di4484bna1tttgn4na0za9fe4apgnkgjhcmc5b4mlqp5yzmnwkyf8meegow8iri4q2cz89a5pm3i7m5d7; Path=/

centos_node.1,centos_node.2,centos_node.3

Get instance names of a node in Run.

HTTP Request

GET https://nuv.la/run/<run-uuid>/<node-name>

URL Parameters

Parameter Required Description
run-uuid true Run unique identifier - e.g. fa3b9652-9dac-49e2-9573-b761777c8238.
node-name true Node name - e.g. centos_node.

Set a node instance (VM) runtime parameter

curl https://nuv.la/run/cce5ac6d-5465-4773-9875-66f21c65e15e/centos_node.1:my_parameter -d my_value -u <user>:<password> -X PUT

The above command sets my_value on the runtime parameter my_parameter of the node instance centos_node.1. On success, the return code is 200. If the body of the request is not provided or set to an empty string, the parameter is said to be unset. Please refer to the "Get a node instance (VM) runtime parameter" section for handling the cases of the parameters either being not yet set or unset.

HTTP Request

PUT https://nuv.la/run/<run-uuid>/<node-instance-name>:<parameter-name>

URL Parameters

Parameter Required Description
run-uuid true Run unique identifier - e.g. fa3b9652-9dac-49e2-9573-b761777c8238.
node-instance-name true Node instance name - e.g. centos_node.1
parameter-name true Parameter name - e.g. my_parameter

Body Parameters

Parameter Required Description
value false The actual value of the parameter to be set

Get a node instance (VM) runtime parameter

curl https://nuv.la/run/cce5ac6d-5465-4773-9875-66f21c65e15e/centos_node.1:my_parameter -u <user>:<password>

On success, the above command returns the value of the runtime parameter my_parameter of the node instance centos_node.1 (if the parameter and the node instance are present), and the value is returned as Content-Type: text/plain; charset=UTF-8 (not XML).

HTTP/1.1 200 OK
Server: nginx/1.8.0
Date: Wed, 06 May 2015 15:32:46 GMT
Content-Type: text/plain; charset=UTF-8
Content-Length: 4
Connection: keep-alive
Accept-Ranges: bytes
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
Set-Cookie: com.sixsq.slipstream.cookie=com.sixsq.idtype=local&com.sixsq.identifier=test&com.sixsq.expirydate=1430969566000&com.sixsq.signature=3nqx5dj24tw4bwocqem5jy5eel2g7ebszwtuj1vli9j316trq6023760pwdp6uzmi8bdtrzwc0addw1p0yff5ube4dntiydt5st; Path=/; Expires=Thu, 07 May 2015 03:32:46 GMT
Strict-Transport-Security: max-age=31536000; includeSubdomains

my_value

For better handling of the error cases the “Accept: application/xml” header should be used. In case either node instance or parameter does not exist, 404 error code is returned and the error message in the XML format looks like the following:

<error code="404" reason="Not Found" detail="Unknown key centos_node.1:my_parameter" specificationUri="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5">
Unknown key centos_node.1:my_parameter
</error>

In case the parameter value is not yet set (i.e., it’s an empty string), the server returns 412 - Precondition Failed:

<error code="412" reason="Precondition Failed" detail="key centos_node.1:my_parameter not yet set" specificationUri="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.13">
key centos_node.1:my_parameter not yet set
</error>

HTTP Request

GET https://nuv.la/run/<run-uuid>/<node-instance-name>:<parameter-name>

URL Parameters

Parameter Required Description
run-uuid true Run unique identifier - e.g. fa3b9652-9dac-49e2-9573-b761777c8238.
node-instance-name true Node instance name - e.g. centos_node.1
parameter-name true Parameter name - e.g. my_parameter

Deployment (CIMI)

This is a prototype resource that will eventually replace the legacy Run resource. This should not be used in production at this time.

DeploymentTemplate (CIMI)

This is a prototype resource that allows the Deployment resource to be created. This resource should not be used in production at this time.

Event (CIMI)

Event resources provide a timestamp for the occurrence of some action. These are used within the SlipStream server to mark changes in the lifecycle of a cloud application and for other important actions.

Some of the lifecycle changes that generate events are:

List all Events

curl https://nuv.la/api/event/ -b cookie-user.txt -D -

The above command returns json structured like this:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2284
Server: http-kit
Date: Thu, 19 Mar 2015 13:15:48 GMT

{
  "events" : [ {
    "content" : {
      "resource" : {
        "href" : "Run/45614147-aed1-4a24-889d-6365b0b1f2cd"
      },
      "state" : "Started"
    },
    "updated" : "2015-03-19T09:39:38.238Z",
    "type" : "state",
    "created" : "2015-03-19T09:39:38.238Z",
    "id" : "Event/0d78db78-1b98-4bd1-ba14-bf378da68a66",
    "severity" : "medium",
    "acl" : {
      "owner" : {
        "type" : "USER",
        "principal" : "joe"
      },
      "rules" : [ {
        "type" : "ROLE",
        "principal" : "ANON",
        "right" : "ALL"
      } ]
    },
    "operations" : [ {
      "rel" : "http://sixsq.com/slipstream/1/Action/delete",
      "href" : "Event/0d78db78-1b98-4bd1-ba14-bf378da68a66"
    } ],
    "resourceURI" : "http://sixsq.com/slipstream/1/Event",
    "timestamp" : "2015-01-10T08:20:00.0Z"
  } ],
  "operations" : [ {
    "rel" : "http://sixsq.com/slipstream/1/Action/add",
    "href" : "Event"
  } ],
  "acl" : {
    "rules" : [ {
      "type" : "ROLE",
      "right" : "ALL",
      "principal" : "ANON"
    } ],
    "owner" : {
      "type" : "ROLE",
      "principal" : "ADMIN"
    }
  },
  "resourceURI" : "http://sixsq.com/slipstream/1/EventCollection",
  "id" : "Event",
  "count" : 1
}

Lists all events accessible by the authenticated user. A user has the right to see an event if she is the owner, or is a super user.

HTTP Request

GET https://nuv.la/api/event/

Create an Event

curl https://nuv.la/api/event -d "{ \"acl\": {\"owner\": {\"type\": \"USER\", \"principal\": \"joe\"},    \"rules\": [{\"type\": \"ROLE\", \"prinipal\": \"ANON\", \"right\": \"ALL\"}]},    \"id\": \"123\",    \"created\" :  \"2015-01-16T08:20:00.0Z\",    \"updated\" : \"2015-01-16T08:20:00.0Z\",    \"resourceURI\" : \"http://slipstream.sixsq.com/ssclj/1/Event\",    \"timestamp\": \"2015-01-10T08:20:00.0Z\",    \"content\" :  { \"resource\":  {\"href\": \"Run/45614147-aed1-4a24-889d-6365b0b1f2cd\"},    \"state\" : \"Started\" } ,    \"type\": \"state\",    \"severity\": \"medium\"}" -X POST -H "Content-Type: application/json" -b cookie-user.txt -D -

The above command returns a json structured like this:

HTTP/1.1 201 Created
Location: Event/257cf1bd-1397-4296-8124-bb2213425b6e
Content-Type: application/json
Content-Length: 152
Server: http-kit
Date: Thu, 19 Mar 2015 12:47:38 GMT

{
  "status" : 201,
  "message" : "created Event/257cf1bd-1397-4296-8124-bb2213425b6e",
  "resource-id" : "Event/257cf1bd-1397-4296-8124-bb2213425b6e"
}

In case of error (e.g invalid value for severity), the following json is returned (note that the message details the origin of the problem):

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 232
Server: http-kit
Date: Thu, 19 Mar 2015 13:48:11 GMT

{
  "status" : 400,
  "message" : "resource does not satisfy defined schema: {:acl {:rules [{:prinicpal disallowed-key, :principal missing-required-key}]}, :severity (not (#{\"low\" \"high\" \"medium\" \"critical\"} \"urgent\"))}"
}

Create an event that contains information (mainly timestamp and state) related to a target resource.

HTTP Request

POST https://nuv.la/api/event

Body Parameters

Parameter Required Description
timestamp true The timestamp (GMT time) of the event (not to be confused with created and updated timestamps of the resource representing the event)
content true Structure containing the resource reference (i.e the target of this event) and its state
type true Accepted values: state and alarm
severity true Accepted values: critical, high, medium and low

Get an Event

curl https://nuv.la/api/event/4605ee06-ccda-48f5-a481-23c6ab296b0d -b cookie-user.txt -D -

The above command returns a json structured like this:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 869
Server: http-kit
Date: Thu, 19 Mar 2015 13:17:06 GMT

{
  "content" : {
    "resource" : {
      "href" : "Run/45614147-aed1-4a24-889d-6365b0b1f2cd"
    },
    "state" : "Started"
  },
  "updated" : "2015-03-19T12:46:16.766Z",
  "type" : "state",
  "created" : "2015-03-19T12:46:16.766Z",
  "id" : "Event/4605ee06-ccda-48f5-a481-23c6ab296b0d",
  "severity" : "medium",
  "acl" : {
    "owner" : {
      "type" : "USER",
      "principal" : "joe"
    },
    "rules" : [ {
      "type" : "ROLE",
      "principal" : "ANON",
      "right" : "ALL"
    } ]
  },
  "operations" : [ {
    "rel" : "http://sixsq.com/slipstream/1/Action/delete",
    "href" : "Event/4605ee06-ccda-48f5-a481-23c6ab296b0d"
  } ],
  "resourceURI" : "http://sixsq.com/slipstream/1/Event",
  "timestamp" : "2015-01-10T08:20:00.0Z"
}

Get a specific event.

HTTP Request

GET https://nuv.la/api/event/<event-uuid>

Delete an Event

curl -X DELETE  https://nuv.la/api/event/85d787ea-a06e-4577-bf2b-1e681d5769a2 -b cookie-user.txt -D -

The above command returns a json structured like this:

HTTP/1.1 204 No Content
Content-Type: application/json
Content-Length: 152
Server: http-kit
Date: Thu, 19 Mar 2015 13:26:27 GMT

When providing an invalid event-uuid, here is the response:

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 102
Server: http-kit
Date: Thu, 19 Mar 2015 13:35:57 GMT

{
  "status" : 404,
  "message" : "Event/wrong-uuid not found",
  "resource-id" : "Event/wrong-uuid"
}

Delete a specific (the event-uuid is known) event.

HTTP Request

DELETE https://nuv.la/api/event/<event-uuid>

Errors

The SlipStream REST API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request is inconsistent
401 Unauthorized – Your username/password of cookie is wrong
403 Forbidden – You don’t have the rights to perform this action
404 Not Found – The requested resource doesn’t exist
405 Method Not Allowed – You tried to access a resource with an invalid method
406 Not Acceptable – You requested a format that is not supported
409 The request could not be processed because of conflict in the request, such as an edit conflict in the case of multiple updates.
413 The request is larger than the server is willing or able to process.
418 I’m a teapot – The all time classic :-)
429 Too Many Requests – The user has sent too many requests in a given amount of time.
500 Internal Server Error – We have a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintenance. Please try again later.

Deprecated Resources

The following sections describe the details of older, deprecated resources. These resource may still work, but developers are encouraged to move to the given replacement resources.

Legacy User Resource

https://nuv.la/user

The legacy user resource is deprecated. All of the user information has been migrated to CIMI resources; use those in preference to this resource. Internally, this resource is implemented via the CIMI resources.