Overview

HTTP verbs

RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

PUT

Used to update an existing resource, including partial updates

DELETE

Used to delete an existing resource

HTTP status codes

RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

The request completed successfully

201 Created

A new resource has been created successfully. The resource’s URI is available from response body will include the location of the resource

202 Accepted

An update to an existing resource has been accepted successfully

204 No Content

The request has been applied successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

401 Unauthorized

The request requires user authentication. The response body and the headers will include an error providing further information

403 Forbidden

The server understood the request, but is refusing to fulfill it. The response body and the headers will include an error providing further information

404 Not Found

The requested resource did not exist

409 Conflict

The request generated a conflict. The response body will include an error providing further information

500 Internal Server Error

The request generated a server error. The response body will include an error providing further information

Errors

Whenever an error response (status code >= 400) is returned, the body will contain a JSON object that describes the problem. The error object has the following structure:

Path Type Description

code

Number

The HTTP status code

title

String

The HTTP status name

message

String

A displayable message describing the error

For example, a request that attempts to apply a not existing deployment will produce a 404 Not Found response:

HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 68

{
  "code" : 404,
  "title" : "Not Found",
  "message" : "Message"
}

Metadata

The Orchestrator adds hypermedia and pagination metadata in the responses.

Hypermedia

The Orchestrator uses hypermedia links (atom link) to other resources in the responses. Atom link element defines a reference from an entry or feed to a Web resource.

Path Type Description

links[].rel

String

means relationship. In this case, it’s a self-referencing hyperlink.More complex systems might include other relationships.

links[].href

String

Is a complete URL that uniquely defines the resource.

Links to other resource:

Relation Description

self

Self-referencing hyperlink

template

Template reference hyperlink

resources

Resources reference hyperlink

When the response is paginated, the response can include also this links:

Relation Description

first

Hyperlink to the first page

prev

Hyperlink to the previous page

self

Self-referencing hyperlink

next

Self-referencing hyperlink

last

Hyperlink to the last page

Pagination

Rather than return everything from a large result, the Orchestrator response are paginated:

Path Type Description

page.size

Number

The size of the page

page.totalElements

Number

The total number of elements

page.totalPages

Number

The total number of the page

page.number

Number

The current page

Authentication

In order to use this APIs the REST client must authenticate via OAuth2 bearer token (RFC 6750)

Example request

$ curl 'http://localhost:8080/deployments?createdBy=7e4f1fe3-d87c-4670-bdb3-1f952ac611b6@https://iam-test.indigo-datacloud.eu/' -i -H 'Accept: application/json' -H 'Authorization: Bearer <access token>'

Authentication header

Name Description

Authorization

OAuth2 bearer token

Deployment

This resource represents a TOSCA template deployment.

Get deployments

A GET request is used to list all the deployments.

Request parameters

Parameter Description

createdBy

Optional parameter to filter the deployments based on who created them. The following values can be used:

  • OIDC_subject@OIDC_issuer: to ask for the deployments of a generic user

  • me: shortcut to ask for the deployments created by the user making the request

Example request

$ curl 'http://localhost:8080/deployments?createdBy=7e4f1fe3-d87c-4670-bdb3-1f952ac611b6@https://iam-test.indigo-datacloud.eu/' -i -H 'Accept: application/json' -H 'Authorization: Bearer <access token>'
GET /deployments?createdBy=7e4f1fe3-d87c-4670-bdb3-1f952ac611b6@https://iam-test.indigo-datacloud.eu/ HTTP/1.1
Accept: application/json
Authorization: Bearer <access token>
Host: localhost:8080

Response structure

Path Type Description

content[].uuid

String

The unique identifier of a resource

content[].creationTime

String

Creation date-time (http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)

content[].updateTime

String

Update date-time

content[].status

String

The status of the deployment. (http://indigo-dc.github.io/orchestrator/apidocs/it/reply/orchestrator/enums/Status.html)

content[].statusReason

String

Verbose explanation of reason that lead to the deployment status (Present only if the deploy is in some error status)

content[].task

String

The current step of the deployment process. (http://indigo-dc.github.io/orchestrator/apidocs/it/reply/orchestrator/enums/Task.html)

content[].createdBy

Object

The OIDC info of the deployment’s creator.

content[].callback

String

The endpoint used by the orchestrator to notify the progress of the deployment process.

content[].outputs

Object

The outputs of the TOSCA document

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1944

{
  "links" : [ {
    "rel" : "self",
    "href" : "http://localhost:8080/deployments?createdBy=7e4f1fe3-d87c-4670-bdb3-1f952ac611b6@https://iam-test.indigo-datacloud.eu/"
  } ],
  "content" : [ {
    "uuid" : "49b4e59e-632b-47e3-aaab-8695a102b344",
    "creationTime" : "2018-11-29T00:27+0000",
    "updateTime" : "2018-11-29T00:27+0000",
    "status" : "CREATE_FAILED",
    "statusReason" : "Some reason",
    "outputs" : { },
    "task" : "NONE",
    "callback" : "http://localhost",
    "createdBy" : {
      "issuer" : "https://iam-test.indigo-datacloud.eu/",
      "subject" : "7e4f1fe3-d87c-4670-bdb3-1f952ac611b6"
    },
    "links" : [ {
      "rel" : "self",
      "href" : "http://localhost:8080/deployments/49b4e59e-632b-47e3-aaab-8695a102b344"
    }, {
      "rel" : "resources",
      "href" : "http://localhost:8080/deployments/49b4e59e-632b-47e3-aaab-8695a102b344/resources"
    }, {
      "rel" : "template",
      "href" : "http://localhost:8080/deployments/49b4e59e-632b-47e3-aaab-8695a102b344/template"
    } ]
  }, {
    "uuid" : "340c7ef0-ba80-4aab-a21b-3e80c8161261",
    "creationTime" : "2018-11-29T00:27+0000",
    "updateTime" : "2018-11-29T00:27+0000",
    "status" : "CREATE_COMPLETE",
    "outputs" : { },
    "task" : "NONE",
    "callback" : "http://localhost",
    "createdBy" : {
      "issuer" : "https://iam-test.indigo-datacloud.eu/",
      "subject" : "7e4f1fe3-d87c-4670-bdb3-1f952ac611b6"
    },
    "links" : [ {
      "rel" : "self",
      "href" : "http://localhost:8080/deployments/340c7ef0-ba80-4aab-a21b-3e80c8161261"
    }, {
      "rel" : "resources",
      "href" : "http://localhost:8080/deployments/340c7ef0-ba80-4aab-a21b-3e80c8161261/resources"
    }, {
      "rel" : "template",
      "href" : "http://localhost:8080/deployments/340c7ef0-ba80-4aab-a21b-3e80c8161261/template"
    } ]
  } ],
  "page" : {
    "size" : 10,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

Create deployment

A POST request is used to create a deployment.

Request Fields

Path Type Description

template

String

A string containing a TOSCA YAML-formatted template

parameters

Object

The input parameters of the deployment(Map of String, Object)

callback

String

The deployment callback URL (optional)

maxProvidersRetry

Number

The maximum number Cloud providers on which attempt to create the deployment (Optional, default unbounded)

keepLastAttempt

Boolean

Whether the Orchestrator, in case of failure, will keep the resources of the last deploy attempt or not (Optional, default false)

Example request

$ curl 'http://localhost:8080/deployments' -i -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer <access token>' -d '{
  "template" : "template",
  "parameters" : {
    "cpus" : 1
  },
  "callback" : "http://localhost:8080/callback",
  "maxProvidersRetry" : 1,
  "keepLastAttempt" : false
}'
POST /deployments HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access token>
Host: localhost:8080
Content-Length: 173

{
  "template" : "template",
  "parameters" : {
    "cpus" : 1
  },
  "callback" : "http://localhost:8080/callback",
  "maxProvidersRetry" : 1,
  "keepLastAttempt" : false
}

Response structure

Path Type Description

uuid

String

The unique identifier of a resource

creationTime

String

Creation date-time (http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)

updateTime

String

Update date-time (http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)

status

String

The status of the deployment. (http://indigo-dc.github.io/orchestrator/apidocs/it/reply/orchestrator/enums/Status.html)

task

String

The current step of the deployment process. (http://indigo-dc.github.io/orchestrator/apidocs/it/reply/orchestrator/enums/Task.html)

outputs

Object

The outputs of the TOSCA document

callback

String

The endpoint used by the orchestrator to notify the progress of the deployment process.

Example response

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Content-Length: 644

{
  "uuid" : "1c2ca247-002e-43f9-b7c3-a7548c8e1489",
  "creationTime" : "2018-11-29T00:27+0000",
  "updateTime" : "2018-11-29T00:27+0000",
  "status" : "CREATE_IN_PROGRESS",
  "outputs" : { },
  "task" : "NONE",
  "callback" : "http://localhost:8080/callback",
  "links" : [ {
    "rel" : "self",
    "href" : "http://localhost:8080/deployments/1c2ca247-002e-43f9-b7c3-a7548c8e1489"
  }, {
    "rel" : "resources",
    "href" : "http://localhost:8080/deployments/1c2ca247-002e-43f9-b7c3-a7548c8e1489/resources"
  }, {
    "rel" : "template",
    "href" : "http://localhost:8080/deployments/1c2ca247-002e-43f9-b7c3-a7548c8e1489/template"
  } ]
}

Get deployment

A GET request is used to retrieve the deployment from the id.

Example request

$ curl 'http://localhost:8080/deployments/mmd34483-d937-4578-bfdb-ebe196bf82dd' -i -H 'Authorization: Bearer <access token>'
GET /deployments/mmd34483-d937-4578-bfdb-ebe196bf82dd HTTP/1.1
Authorization: Bearer <access token>
Host: localhost:8080

Response structure

Path Type Description

uuid

String

The unique identifier of a resource

creationTime

String

Creation date-time (http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)

updateTime

String

Update date-time

status

String

The status of the deployment. (http://indigo-dc.github.io/orchestrator/apidocs/it/reply/orchestrator/enums/Status.html)

statusReason

String

Verbose explanation of reason that lead to the deployment status (Present only if the deploy is in some error status)

task

String

The current step of the deployment process. (http://indigo-dc.github.io/orchestrator/apidocs/it/reply/orchestrator/enums/Task.html)

callback

String

The endpoint used by the orchestrator to notify the progress of the deployment process.

outputs

Object

The outputs of the TOSCA document

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 690

{
  "uuid" : "mmd34483-d937-4578-bfdb-ebe196bf82dd",
  "creationTime" : "2018-11-29T00:27+0000",
  "updateTime" : "2018-11-29T00:27+0000",
  "status" : "CREATE_FAILED",
  "statusReason" : "Some reason",
  "outputs" : {
    "server_ip" : "10.0.0.1"
  },
  "task" : "NONE",
  "callback" : "http://localhost",
  "links" : [ {
    "rel" : "self",
    "href" : "http://localhost:8080/deployments/mmd34483-d937-4578-bfdb-ebe196bf82dd"
  }, {
    "rel" : "resources",
    "href" : "http://localhost:8080/deployments/mmd34483-d937-4578-bfdb-ebe196bf82dd/resources"
  }, {
    "rel" : "template",
    "href" : "http://localhost:8080/deployments/mmd34483-d937-4578-bfdb-ebe196bf82dd/template"
  } ]
}

Update deployment

A PUT request is used to update the deployment from the id.

Example request

$ curl 'http://localhost:8080/deployments/mmd34483-d937-4578-bfdb-ebe196bf82dd' -i -X PUT -H 'Content-Type: application/json' -H 'Authorization: Bearer <access token>' -d '{
  "template" : "template",
  "parameters" : {
    "cpus" : 1
  },
  "callback" : "http://localhost:8080/callback",
  "maxProvidersRetry" : 1,
  "keepLastAttempt" : false
}'
PUT /deployments/mmd34483-d937-4578-bfdb-ebe196bf82dd HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access token>
Host: localhost:8080
Content-Length: 173

{
  "template" : "template",
  "parameters" : {
    "cpus" : 1
  },
  "callback" : "http://localhost:8080/callback",
  "maxProvidersRetry" : 1,
  "keepLastAttempt" : false
}

Example response

HTTP/1.1 202 Accepted

Delete deployment

A DELETE request is used to delete the deployment from the id.

Example request

$ curl 'http://localhost:8080/deployments/mmd34483-d937-4578-bfdb-ebe196bf82dd' -i -X DELETE -H 'Authorization: Bearer <access token>'
DELETE /deployments/mmd34483-d937-4578-bfdb-ebe196bf82dd HTTP/1.1
Authorization: Bearer <access token>
Host: localhost:8080

Example response

HTTP/1.1 204 No Content

Get template

A GET request is used to retrieve the template associated to a deployment.

Example request

$ curl 'http://localhost:8080/deployments/5fad7e6b-06c4-489f-b746-5b83ffbb034e/template' -i -H 'Authorization: Bearer <access token>'
GET /deployments/5fad7e6b-06c4-489f-b746-5b83ffbb034e/template HTTP/1.1
Authorization: Bearer <access token>
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: text/plain;charset=UTF-8
Content-Length: 1266

tosca_definitions_version: tosca_simple_yaml_1_0

repositories:
  indigo_repository:
    description: INDIGO Custom types repository
    url: https://raw.githubusercontent.com/indigo-dc/tosca-types/master/

imports:
  - indigo_custom_types:
      file: custom_types.yaml
      repository: indigo_repository

description: >
  TOSCA test for launching a Galaxy Server also configuring the bowtie2
  tool using Galaxy Tool Shed.

topology_template:

  node_templates:

    bowtie2_galaxy_tool:
      type: tosca.nodes.indigo.GalaxyShedTool
      properties:
        name: bowtie2
        owner: devteam
        tool_panel_section_id: ngs_mapping
      requirements:
        - host: galaxy

    galaxy:
      type: tosca.nodes.indigo.GalaxyPortal
      requirements:
        - lrms: local_lrms

    local_lrms:
      type: tosca.nodes.indigo.LRMS.FrontEnd.Local
      requirements:
        - host: galaxy_server

    galaxy_server:
      type: tosca.nodes.indigo.Compute
      properties:
        public_ip: yes
      capabilities:
        host:
          properties:
            num_cpus: 1
            mem_size: 1 GB
        os:
          properties:
            type: linux

  outputs:
    galaxy_url:
      value: { get_attribute: [ galaxy_server, public_address ] }

Resource

This REST resource represents a TOSCA node of the template.

Get Resources

A GET request is used to list all the resources of a deployment.

Example request

$ curl 'http://localhost:8080/deployments/07325c37-4cd3-4363-80f9-a5a61dc5d094/resources' -i -H 'Accept: application/json' -H 'Authorization: Bearer <access token>'
GET /deployments/07325c37-4cd3-4363-80f9-a5a61dc5d094/resources HTTP/1.1
Accept: application/json
Authorization: Bearer <access token>
Host: localhost:8080

Response structure

Path Type Description

content[].uuid

String

The unique identifier of a resource

content[].creationTime

String

Creation date-time (http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)

content[].updateTime

String

Update date-time (http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)

content[].state

String

The status of the resource. (http://indigo-dc.github.io/orchestrator/apidocs/it/reply/orchestrator/enums/NodeStates.html)

content[].toscaNodeType

String

The type of the represented TOSCA node

content[].toscaNodeName

String

The name of the represented TOSCA node

content[].requiredBy

Array

A list of nodes that require this resource

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1463

{
  "links" : [ {
    "rel" : "self",
    "href" : "http://localhost:8080/deployments/07325c37-4cd3-4363-80f9-a5a61dc5d094/resources?page=0&size=10&sort=createdAt,desc"
  } ],
  "content" : [ {
    "uuid" : "646ed266-26bd-43a6-8a37-4010b9dacf00",
    "creationTime" : "2018-11-29T00:27+0000",
    "updateTime" : "2018-11-29T00:27+0000",
    "state" : "CREATING",
    "toscaNodeType" : "tosca.nodes.Compute",
    "toscaNodeName" : "node_0",
    "requiredBy" : [ ],
    "links" : [ {
      "rel" : "deployment",
      "href" : "http://localhost:8080/deployments/07325c37-4cd3-4363-80f9-a5a61dc5d094"
    }, {
      "rel" : "self",
      "href" : "http://localhost:8080/deployments/07325c37-4cd3-4363-80f9-a5a61dc5d094/resources/646ed266-26bd-43a6-8a37-4010b9dacf00"
    } ]
  }, {
    "uuid" : "7e65a064-61a6-4d44-b86d-2041b136e441",
    "creationTime" : "2018-11-29T00:27+0000",
    "updateTime" : "2018-11-29T00:27+0000",
    "state" : "CREATING",
    "toscaNodeType" : "tosca.nodes.Compute",
    "toscaNodeName" : "node_1",
    "requiredBy" : [ ],
    "links" : [ {
      "rel" : "deployment",
      "href" : "http://localhost:8080/deployments/07325c37-4cd3-4363-80f9-a5a61dc5d094"
    }, {
      "rel" : "self",
      "href" : "http://localhost:8080/deployments/07325c37-4cd3-4363-80f9-a5a61dc5d094/resources/7e65a064-61a6-4d44-b86d-2041b136e441"
    } ]
  } ],
  "page" : {
    "size" : 10,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

Get resource

A GET request is used to retrieve the resource from the id.

Example request

$ curl 'http://localhost:8080/deployments/26f2bee8-3463-475f-b2f3-a6d8053e4d03/resources/a7b810cf-e8b7-4906-852c-f8bfa2182f96' -i -H 'Authorization: Bearer <access token>'
GET /deployments/26f2bee8-3463-475f-b2f3-a6d8053e4d03/resources/a7b810cf-e8b7-4906-852c-f8bfa2182f96 HTTP/1.1
Authorization: Bearer <access token>
Host: localhost:8080

Response structure

Path Type Description

uuid

String

The unique identifier of a resource

creationTime

String

Creation date-time (http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)

updateTime

String

Update date-time (http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)

state

String

The status of the resource. (http://indigo-dc.github.io/orchestrator/apidocs/it/reply/orchestrator/enums/NodeStates.html)

toscaNodeType

String

The type of the represented TOSCA node

toscaNodeName

String

The name of the represented TOSCA node

requiredBy

Array

A list of nodes that require this resource

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 588

{
  "uuid" : "a7b810cf-e8b7-4906-852c-f8bfa2182f96",
  "creationTime" : "2018-11-29T00:27+0000",
  "updateTime" : "2018-11-29T00:27+0000",
  "state" : "CREATING",
  "toscaNodeType" : "tosca.nodes.Compute",
  "toscaNodeName" : "node_b97413cd-d822-41cd-87c2-8e359bb18e89",
  "requiredBy" : [ ],
  "links" : [ {
    "rel" : "deployment",
    "href" : "http://localhost:8080/deployments/26f2bee8-3463-475f-b2f3-a6d8053e4d03"
  }, {
    "rel" : "self",
    "href" : "http://localhost:8080/deployments/26f2bee8-3463-475f-b2f3-a6d8053e4d03/resources/a7b810cf-e8b7-4906-852c-f8bfa2182f96"
  } ]
}