NAV
shell

SlipStream API Reference

Introduction

Welcome to the SlipStream API. You can use our API to access SlipStream endpoints in order to manipulate different REST resources, including project, image, deployment, available as module, as well as run and user.

This API focuses on the REST service offered and has been documented in Bash. You can view code examples in the dark area to the right.

This API documentation page was created with Slate. Feel free to report any snags in the document in GitHub.

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:

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

is equivalent to

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

Resource Oriented Architecture (ROA)

SlipStream’s REST design was inspired from Richardson and Ruby’s excellent book: RESTful Web Services. They present the Resource Oriented Architecture (ROA) concept, which guided several design choices, including the resources-based architecture underpinning SlipStream. For example, each version of an image, deployment and project can be uniquely identified via a unique URI.

Authentication

With the exception of the login page, all resources require authentication.

SlipStream supports Cookies authentication and Basic Authentication (deprecated, soon to be removed). Resources under /api namespace suport only Cookies authentication.

To generate a time limited cookie, use the /auth/login resource.

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

The above command returns a header structured like this:

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

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

Event

The resources under /api namespace do not support basic authentication and require an authentication cookie.

This resource can be created for example to log for a given run the following events:

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

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.

Service Attribute

This resource represents the meta-information of each attribute of a Service Offer instance (see Service Offer resource).

List Service Attribute resource

This returns the collection of Service Attribute resources.

HTTP Request

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

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

The above command returns a json structured like this (truncated for readability):

HTTP/1.1 200 OK
Content-Type: application/json
Server: Aleph/0.4.0
Connection: Keep-Alive
Date: Tue, 09 Feb 2016 12:32:38 GMT
content-length: 22221

{
  "acl" : {
    "owner" : {
      "principal" : "ADMIN",
      "type" : "ROLE"
    },
    "rules" : [ {
      "principal" : "USER",
      "type" : "ROLE",
      "right" : "MODIFY"
    } ]
  },
  "resourceURI" : "http://sixsq.com/slipstream/1/ServiceAttributeCollection",
  "id" : "service-attribute",
  "operations" : [ {
    "rel" : "http://sixsq.com/slipstream/1/Action/add",
    "href" : "service-attribute"
  } ],
  "count" : 31,
  "service-attribute" : [ {
    "minor-version" : 0,
    "updated" : "2016-02-09T12:11:27.735Z",
    "major-version" : 1,
    "type" : "String",
    "created" : "2016-02-09T12:11:27.735Z",
    "en" : {
      "name" : "price.storage.per.hour",
      "categories" : [ "Price" ],
      "description" : "Nature: the price for use of a unit (e.g. 1 GB) of storage per hour; Value: the price in euros, e.g. \u20AC0.0005; Explanation: note that is possible that storage is either associated with a particular VM or as a generally-available resource"
    },
    "id" : "attribute/12e5c0ea-fbe5-4d39-ba3b-e919789078b0",
    "acl" : {
      "owner" : {
        "principal" : "ADMIN",
        "type" : "ROLE"
      }
    },
    "operations" : [ {
      "rel" : "http://sixsq.com/slipstream/1/Action/edit",
      "href" : "attribute/12e5c0ea-fbe5-4d39-ba3b-e919789078b0"
    }, {
      "rel" : "http://sixsq.com/slipstream/1/Action/delete",
      "href" : "attribute/12e5c0ea-fbe5-4d39-ba3b-e919789078b0"
    } ],
    "resourceURI" : "http://sixsq.com/slipstream/1/Attribute",
    "uri" : "http://schema.hnx.helix-nebula.eu/price.storage.per.hour",
    "patch-version" : 0,
    "normative" : true
  },
  ...

Create an Service Attribute resource

HTTP REQUEST

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

Body Parameters

Parameter Required Description
major-version true Major version number of the schema
minor-version true Minor version number of the schema
patch-version true Patch version number of the schema
normative true
type true Type of the data: String, …
uri true URI of this schema
en.name true Name of this attribute
en.categories true List of categories
en.description true Description of this attribute
curl -X POST -H "Content-Type: application/json" https://nuv.la/api/service-attribute -d "{\"major-version\": 1, \"minor-version\": 0, \"patch-version\": 0, \"normative\": true, \"type\": \"String\", \"uri\": \"http://schema.hnx.helix-nebula.eu/hyper.price.per.hour\", \"en\": {\"name\": \"hyper.price.per.hour\",\"categories\": [\"Price\"],\"description\": \"Nature: the price for a Hyper type instance with 16 CPU and 128 GB RAM\"}}" -b cookie-user.txt -D -

The above command returns a json response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: service-attribute/d77a553b-7332-48a0-b653-3b2b4b336049
Server: Aleph/0.4.0
Connection: Keep-Alive
Date: Tue, 09 Feb 2016 12:55:09 GMT
content-length: 160

{
  "status" : 201,
  "message" : "created service-attribute/d77a553b-7332-48a0-b653-3b2b4b336049",
  "resource-id" : "service-attribute/d77a553b-7332-48a0-b653-3b2b4b336049"
}

Delete an Service Attribute resource

HTTP REQUEST

DELETE https://nuv.la/api/service-attribute/<id>

curl -X DELETE -H "Content-Type: application/json" https://nuv.la/api/service-attribute/d77a553b-7332-48a0-b653-3b2b4b336049 -b cookie-user.txt -D -

The above command returns a json response:

HTTP/1.1 204 No Content
Content-Type: application/json
Server: Aleph/0.4.0
Connection: Keep-Alive
Date: Tue, 09 Feb 2016 13:03:31 GMT
content-length: 160

Service Offer

Provides detailed capability information for each available cloud.

Get the Service Offer

HTTP REQUEST

GET https://nuv.la/api/service-offer

curl -X GET -H "Content-Type: application/json" https://nuv.la/api/service-offer -b cookie-user.txt -D -

The above command returns a json response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Aleph/0.4.0
Connection: Keep-Alive
Date: Tue, 09 Feb 2016 18:04:39 GMT
content-length: 20147

{
  "acl" : {
    "owner" : {
      "principal" : "ADMIN",
      "type" : "ROLE"
    },
    "rules" : [ {
      "principal" : "USER",
      "type" : "ROLE",
      "right" : "MODIFY"
    } ]
  },
  "resourceURI" : "http://sixsq.com/slipstream/1/ServiceOfferCollection",
  "id" : "service-offer",
  "operations" : [ {
    "rel" : "http://sixsq.com/slipstream/1/Action/add",
    "href" : "service-offer"
  } ],
  "count" : 12,
  "serviceOffers" : [ {
    "connector" : {
      "href" : "t-systems-de1-indigo-1"
    },
    "http://schema.a.b.c/suppliers.catalog" : "",
    "http://schema.a.b.c/single.vm.storage.volatile" : "",
    "http://schema.a.b.c/single.vm.storage.persistent" : "",
    "http://schema.a.b.c/single.vm.max.ram" : "",
    "http://schema.a.b.c/overall.capacity.cpu" : "",
    "http://schema.a.b.c/price.charging.period" : "",
    "http://schema.a.b.c/price.ram.per.hour" : "",
    "updated" : "2016-02-09T18:00:22.387Z",
    "created" : "2016-02-09T18:00:22.387Z",
    "http://schema.a.b.c/price.charging.unit" : "",
    "http://schema.a.b.c/overall.capacity.storage" : "",
    "http://schema.a.b.c/location" : "",
    "id" : "service-info/023285da-7be4-4931-90f5-c50baadc58a4",
    "http://schema.a.b.c/price.cpu.per.hour" : "",
    "http://schema.a.b.c/single.vm.min.cpu" : "",
    "acl" : {
      "owner" : {
        "principal" : "ADMIN",
        "type" : "ROLE"
      },
      "rules" : [ {
        "principal" : "USER",
        "type" : "ROLE",
        "right" : "VIEW"
      } ]
    },
    "resourceURI" : "http://sixsq.com/slipstream/1/ServiceInfo",
    "http://schema.a.b.c/price.io" : "",
    "http://schema.a.b.c/overall.capacity.ram" : "",
    "http://schema.a.b.c/single.vm.max.cpu" : "",
    "http://schema.a.b.c/single.vm.min.ram" : "",
    "http://schema.a.b.c/price.storage.per.hour" : ""
  }
  ...

Create a Service Offer

HTTP REQUEST

POST https://nuv.la/api/service-offer

Body Parameters

Parameter Required Description
connector.href true The cloud name
uri of an attribute 1 false Value of the attribute for this cloud
uri of an attribute 2 false Value of the attribute for this cloud
false

Delete a Service Offer

HTTP REQUEST

DELETE https://nuv.la/api/service-offer

The new resource

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.

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.