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 actions 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.

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

Any other action listed in the operations section of a response will use the HTTP POST method to the provided URL.

Note that there are two CIMI add (create) patterns: one that uses a template to create the resource and another that creates a resource without a template. 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), 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.

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. 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)

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.

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

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>

Usage (CIMI)

Represents the summary of cloud usage records for a given user and cloud, on a specific period.

List all Usage

The collection of usage records (most recent are listed first) is returned filtered with the provided authentication. (Only resources for the given user are returned.)

HTTP Request

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

curl https://nuv.la/api/usage -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: 1511
Server: http-kit
Date: Mon, 22 Jun 2015 08:49:33 GMT

{
  "usages" : [ {
    "usage" : {
      "DISK" : {
        "unit_minutes" : 86400.0
      }
    },
    "end_timestamp" : "2017-09-26T00:00:00.000Z",
    "start_timestamp" : "2017-09-25T00:00:00.000Z",
    "cloud" : "cloud-8",
    "user" : "user-1",
    "acl" : {
      "owner" : {
        "type" : "USER",
        "principal" : "user-1"
      },
      "rules" : [ {
        "type" : "USER",
        "principal" : "user-1",
        "right" : "ALL"
      }, {
        "type" : "ROLE",
        "principal" : "cloud-8",
        "right" : "ALL"
      } ]
    },
    "id" : "Usage/056169bf-ac20-47dd-a7f9-e6b835265a01"
  }, {
    "usage" : {
      "vm" : {
        "unit_minutes" : 1192.0
      }
    },
    "end_timestamp" : "2017-09-26T00:00:00.000Z",
    "start_timestamp" : "2017-09-25T00:00:00.000Z",
    "cloud" : "cloud-5",
    "user" : "user-1",
    "acl" : {
      "owner" : {
        "type" : "USER",
        "principal" : "user-1"
      },
      "rules" : [ {
        "type" : "USER",
        "principal" : "user-1",
        "right" : "ALL"
      }, {
        "type" : "ROLE",
        "principal" : "cloud-5",
        "right" : "ALL"
      } ]
    },
    "id" : "Usage/baf5ce10-9cee-4407-9860-61c2da0c0b13"
  } ],
  "acl" : {
    "rules" : [ {
      "type" : "ROLE",
      "right" : "VIEW",
      "principal" : "ANON"
    } ],
    "owner" : {
      "type" : "ROLE",
      "principal" : "ADMIN"
    }
  },
  "resourceURI" : "http://sixsq.com/slipstream/1/UsageCollection",
  "id" : "Usage",
  "count" : 2
}

Filtering Usage

Filtering on string comparison

To retrieve the usage records for a given cloud, the CIMI filter can be written

$filter=cloud='cloud-name'

Note, however, that such a filter contains characters that must be URL-encoded, and the HTTP request will look like this:

GET https://nuv.la/api/usage?%24filter=cloud%3D%27cloud-name%27

Filtering on date comparison (equality)

To retrieve the usage records for a specific date, the CIMI filter can be written

?$filter=start_timestamp=2015-06-22

Full URL with encoding:

GET https://nuv.la/api/usage?%24filter=start_timestamp%3D2015-06-22

Filtering on date comparison (before or after)

To retrieve the usage records after a specific date, the CIMI filter can be written

?$filter=start_timestamp>2015-06-22

Full URL with encoding:

GET https://nuv.la/api/usage?%24filter=start_timestamp%3E2015-06-22

To filter usage records before a specific date, use < (URL-encoded as %3C) instead.

Filtering with multiple conditions

You can join conditons with and (logical and), or or (logical or).

?$filter=start_timestamp>2015-06-22 and cloud='cloud-name'

Full URL with encoding:

GET https://nuv.la/api/usage?%24filter=start_timestamp%3E2015-06-22%20and%20cloud%3D%27cloud-name%27

These are only some examples, consult the CIMI documentation for an exhaustive list of possibilities.

Paginating Usage

From CIMI Model and RESTful HTTP-based Protocol documentation 4.1.6.2 Subsetting Collections

HTTP Request

GET https://nuv.la/api/usage?%24first=2&%24last=2

will return only the second usage record.

Module

(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.

Run

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

Virtual machines

curl https://nuv.la/vms --user <user>:<password>

The above command returns a body structured like this:

<vms offset="0" limit="20" count="4" totalCount="4" user="super">
   <vm cloud="Exoscale"
      user="test"
      instanceId="96101801-b636-4752-9b04-74ec9a9abbc9"
      state="Booting"
      measurement="2015-04-01 14:34:22.273 CEST"
      isUsable="false"/>
   <vm cloud="Exoscale"
      user="test"
      instanceId="bbb07949-ab64-4556-88fd-f9aed872e9d1"
      state="Running"
      measurement="2015-04-01 14:34:22.273 CEST"
      runUuid="ce3dfa8b-5a13-473b-bdd1-6e40ab71294b"
      runOwner="test"
      ip="185.19.29.126"
      name="testclient.1"
      nodeName="testclient"
      nodeInstanceId="1"
      isUsable="true"/>
   <vm cloud="Exoscale"
      user="test"
      instanceId="ec05f8f2-1f05-48bc-aa33-b99f60b2209b"
      state="Running"
      measurement="2015-04-01 14:33:31.905 CEST"
      runUuid="ce3dfa8b-5a13-473b-bdd1-6e40ab71294b"
      runOwner="test"
      ip="185.19.29.122"
      name="orchestrator-Exoscale"
      isUsable="true"/>
   <vm cloud="Amazon-EC2"
      user="test"
      instanceId="a2ca20d8-9506-42b9-80a3-ce15579591ab"
      state="Running"
      measurement="2015-04-01 14:33:21.426 CEST"
      runUuid="857fc1d4-6206-4d88-8a1c-81d83a117e86"
      runOwner="test"
      ip="185.19.29.123"
      name="machine"
      isUsable="true"/>
</vms>

List status of all virtual machines (VMs), as known by the cloud providers.

HTTP Request

GET https://nuv.la/vms

Query Parameters

Parameter Default value Possible values Description
cloud one cloud Show only the specified Cloud
limit 20 [1 - 500] Set the maximum number of VMs per page.
offset 0 [0 - inf] Offset to navigate through pages.
runUuid one run uuid Show only VMs associated with the specified run uuid
runOwner one username Show only VMs associated with Runs owned by a specific user
user one username Show VMs the specified user can see

<vms> Attributes

Attribute Always present Description
cloud no The Cloud specified in the request if any
limit no The limit specified in the request if any
offset no The offset specified in the request if any
count yes The number of <vm> elements returned
totalCount yes The total number of <vm> elements for this request
runUuid no The Run uuid specified in the request if any
runOwner no The Run owner (username) specified in the request if any
user no The user for which VMs are displayed. Doesn’t exist if VMs for all users are displayed

<vm> Attributes

Attribute Always present Description
cloud yes The Cloud on which the VM is running
user yes The user from which the VM was retrived
instanceId yes The id of the VM on the Cloud
state yes The state of the VM as provided by the Cloud
measurement yes The time when the VM was seen for the first time
runUuid no The uuid of the Run from which the VM is part of
runOwner no The owner of the Run from which the VM is part of
ip no The IP address of the VM
name no The name of the VM in his Run.
nodeName no The name of the node from which the VM is part of in his Run.
nodeInstanceId no The id of the node instance of the VM in his Run.
isUsable no Indicate if the VM is in a state where it can be used.

User

The user resource provides user management.

Get All Users

curl https://nuv.la/user --user <user>:<password>

The above command returns XML structured like this:

<list>
<item name="super"  resourceUri="user/super"  firstName="Super"  lastName="User"  email="super@sixsq.com"  state="ACTIVE"  activeSince="2015-03-11 14:00:57.656 CET"  lastOnline="2015-04-01 14:58:57.466 CEST"  lastExecute="2015-03-12 18:03:13.853 CET"  organization="SixSq"  issuper="true"  online="true" />
</list>

List all users.

HTTP Request

GET https://nuv.la/user

Get a specific user

curl https://nuv.la/user/<user> --user <user>:<password>

The above command returns xml structured like this:

<?xml version="1.0"?>
<user deleted="false" resourceUri="user/super" name="super" email="super@sixsq.com" firstName="Super" lastName="User" organization="SixSq" issuper="true" state="ACTIVE" lastOnline="2015-04-01 17:48:21.661 CEST" lastExecute="2015-04-01 17:19:46.364 CEST" activeSince="2015-03-24 18:07:21.757 CET" creation="2015-03-24 18:07:21.746 CET">
   <parameters class="org.hibernate.collection.internal.PersistentMap">
      <entry>
         <string>General.Verbosity Level</string>
         <parameter name="General.Verbosity Level" description="Level of verbosity" category="General" mandatory="true" type="Enum" readonly="false" order_="30" order="30">
            <instructions><![CDATA[0 - Actions,  1 - Steps,  2 - Details data,  3 - Debugging]]></instructions>
            <enumValues length="4">
               <string>0</string>
               <string>1</string>
               <string>2</string>
               <string>3</string>
            </enumValues>
            <value><![CDATA[0]]></value>
         </parameter>
      </entry>
      <entry>
         <string>test-cloud.username</string>
         <parameter name="test-cloud.username" description="Account username" category="test-cloud" mandatory="true" type="RestrictedString" readonly="false" order_="10" order="10">
            <value><![CDATA[]]></value>
         </parameter>
      </entry>
      <entry>
         <string>General.ssh.public.key</string>
         <parameter name="General.ssh.public.key" description="SSH Public Key(s) (one per line)" category="General" mandatory="true" type="RestrictedText" readonly="false" order_="50" order="50">
            <instructions><![CDATA[Warning: Some clouds may take into account only the first key until SlipStream bootstraps the machine.]]></instructions>
            <value><![CDATA[adasdasd]]></value>
         </parameter>
      </entry>
      <entry>
         <string>test-cloud.password</string>
         <parameter name="test-cloud.password" description="Account password" category="test-cloud" mandatory="true" type="Password" readonly="false" order_="20" order="20">
            <value><![CDATA[]]></value>
         </parameter>
      </entry>
      <entry>
         <string>General.keep-running</string>
         <parameter name="General.keep-running" description="Keep running after deployment" category="General" mandatory="true" type="Enum" readonly="false" order_="15" order="15">
            <instructions><![CDATA[Here you can define if and when SlipStream should leave the application running after performing the deployment. <br/><code>On success</code> is useful for production deployments or long tests. </br><code>On Error</code> might be useful so that resources are consumed only when debugging is needed. <br/><code>Never</code> ensures that SlipStream automatically terminates the application after performing the deployment. <br/>Note: This parameter doesn't apply to <code>scalable deployment</code> Runs and to <code>build image</code> Runs.]]></instructions>
            <enumValues length="4">
               <string>always</string>
               <string>on-success</string>
               <string>on-error</string>
               <string>never</string>
            </enumValues>
            <value><![CDATA[on-success]]></value>
         </parameter>
      </entry>
      <entry>
         <string>General.default.cloud.service</string>
         <parameter name="General.default.cloud.service" description="Default Cloud" category="General" mandatory="true" type="Enum" readonly="false" order_="10" order="10">
            <instructions><![CDATA[Select the cloud that you want to use as the default.]]></instructions>
            <enumValues length="1">
               <string>test-cloud</string>
            </enumValues>
            <value><![CDATA[test-cloud]]></value>
         </parameter>
      </entry>
      <entry>
         <string>General.Timeout</string>
         <parameter name="General.Timeout" description="Execution timeout (in minutes)" category="General" mandatory="true" type="String" readonly="false" order_="40" order="40">
            <instructions><![CDATA[If the execution stays in a transitional state for more than the value of this timeout, the execution is forcefully terminated.]]></instructions>
            <value><![CDATA[30]]></value>
         </parameter>
      </entry>
   </parameters>
</user>

This resource retrieves a specific user.

HTTP Request

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

URL Parameters

Parameter Required Description
user true User name to retrieve

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 that still work with SlipStream. Although these features work, they should not be used for any new code and existing code should migrate to equivalent, non-deprecated resources.

Login

POST https://nuv.la/auth/login

Parameter Required Description
username true Name of the user to authenticate with
password true Password corresponding to the username

This resource allows users to generate a time limited cookie. The value of the cookie corresponds to the Set-Cookie of the response header.

curl -k -s -D - https://nuv.la/auth/login -X POST -d "username=name&password=secret" -c cookie-user.txt

This curl command will store the authentication token inside cookie-user.txt file. This cookie must be used later on (for example with -b option in curl command) to access the API.

Basic authentication (deprecated)

curl https://nuv.la?media=xml -u <user>:<password>

or

curl https://<user>:<password>@slipstream.sixsq.com?media=xml
<welcome>
   <modules>
      <item resourceUri="module/Mebster/48" category="Project" version="48" name="Mebster">
         <authz owner="meb" ownerGet="true" ownerPut="true" ownerPost="false" 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 class="java.util.ArrayList"/>
         </authz>
      </item>
      <item resourceUri="module/SlipStream/280" category="Project" description="SlipStream dog fooding :-)" version="280" name="SlipStream">
         <authz owner="sixsq_dev" ownerGet="true" ownerPut="true" ownerPost="false" ownerDelete="true" ownerCreateChildren="true" groupGet="true" groupPut="true" groupPost="false" groupDelete="false" groupCreateChildren="false" publicGet="false" publicPut="false" publicPost="false" publicDelete="false" publicCreateChildren="false" inheritedGroupMembers="false">
            <groupMembers class="java.util.ArrayList">
               <string>lionel</string>
               <string>konstan</string>
               <string>loomis</string>
               <string>meb</string>
               <string>rob</string>
               <string>sebastien.fievet</string>
            </groupMembers>
         </authz>
      </item>
...

Basic authentication can be tested using simple username/password pair.