REST: Environments related API

List existing environments

Path: /rest/projects/(projectId)/envs
Type: GET
Path parameters

Parameter	Type	Description
projectId	Number	project id of the project envs belong to

Request parameters

Parameter	Type	Mandatory	Description
filter	String	N	Sets filter's values. Currently possible filtering on the status of the environment. Example: filter=statuses[Destroyed,Broken]
sorting	String	N	Sorting by entity field value. By default ordering direction is ascending. Use prefix '~' to produce result in descending order. Example: sorting=~name

Example results

{
    "items": [
        {
         "id" : 1,
         "name" : "test",
         "status" : "Ready",
         "projectId" : 1,
         "configuration" : "Default",
         "creator" : "genesis",
         "creationTime" : 1360066307030,
         "modifiedBy" : "genesis",
         "modificationTime" : 1360066307158,
         "templateName" : "Simple",
         "templateVersion" : "0.1",
         "attributes" : {},
         "links" : [
            {
               "rel" : "self",
               "href" : "http://localhost:8081/rest/projects/1/envs/1",
               "methods" : [
                  "get"
               ],
               "type" : "application/vnd.griddynamics.genesis.Environment+json"
            }
         ],
        }
    ],
    "links" : [
      {
         "rel" : "self",
         "href" : "http://localhost:8081/rest/projects/1/envs",
         "methods" : [
            "post"
         ],
         "type" : "application/vnd.griddynamics.genesis.Environment+json"
      }
   ]
}

Create a new environment

Path: /rest/projects/(projectId)/envs

Type: POST

Parameter	Type	Description
projectId	Number	project id the created env should belong to

Request body structure
Request body consists form a single JSON map contains the following entries:

Entry name	Type	Description
envName	String	Environment name
creator	String	Environment creator name. Parameter is optional. Service uses current user identity to set creator.
templateName	String	Name of the Environment template to use
templateVersion	String	Version of the Environment template to use
configId	Integer	Configuration (environment) id. Optional parameter. If omitted, default environment is used.
variables	Map of String pairs	Creation workflow variable values customized by user
timeToLive	Integer	time to live of the environment (in minutes). optional

Example request :

{
  "envName" : "erlt",
  "templateName" : "Erlang",
  "templateVersion" : "2.0",
  "variables":{"nodesCount": 4}
}

Example results

Sucessful environment creation

{
    "serviceErrors":{},
    "variablesErrors":{},
    "compoundServiceErrors":[],
    "compoundVariablesErrors":[],
    "isSuccess":true
}

Environment creation failed, environment with the same name already exists

{
    "serviceErrors":{
        "envName":"Environment with the same name already exists"
    },
    "variablesErrors":{},
    "compoundServiceErrors":[],
    "compoundVariablesErrors":[],
    "isSuccess":false
}

Environment creation failed, required variable is not set

{
    "serviceErrors":{},
    "variablesErrors":{
        "nodesCount":"Variable 'nodesCount' is not set"
    },
    "compoundServiceErrors":[],
    "compoundVariablesErrors":[],
    "isSuccess":false
}

Delete existing environment

Path: /rest/projects/(projectId)/envs/(environment id)
Type: DELETE

Path parameters:

Parameter	Type	Description
projectId	Number	project id the created env should belong to
environment id	Number	Identifier of the environment to be deleted

Example results: see example results for environment creation

Get environment details

Path: /rest/projects/(projectId)/envs/(environment id)
Type: GET

Path parameters:

Parameter	Type	Description
projectId	Number	project id the env belong to
environment id	Number	Identifier of the environment

**Example results**

{
   "envId" : 1,
   "name" : "test",
   "status" : "Ready",
   "projectId" : 1,
   "creator" : "genesis",
   "templateName" : "Simple",
   "configuration" : "Default",
   "workflows" : [
      {
         "name" : "create",
         "variables" : []
      },
      {
         "name" : "destroy",
         "variables" : []
      }
   ],
   "modifiedBy" : "genesis",
   "destroyWorkflowName" : "destroy",
   "creationTime" : 1360066307030,
   "vms" : [],
   "historyCount" : 1,
   "createWorkflowName" : "create",
   "modificationTime" : 1360066307158,
   "currentWorkflowFinishedActionsCount" : 0,
   "servers" : [],
   "attributes" : {},
   "templateVersion" : "0.1",
   "links" : [
       {
         "rel" : "self",
         "href" : "http://localhost:8081/rest/projects/1/envs/1",
         "methods" : [
            "get",
            "put",
            "delete"
         ],
         "type" : "application/vnd.griddynamics.genesis.EnvironmentDetails+json"
      },
      {
         "rel" : "collection",
         "href" : "http://localhost:8081/rest/projects/1/envs/1/history",
         "methods" : [
            "get"
         ],
         "type" : "application/vnd.griddynamics.genesis.WorkflowHistory+json"
      },
      {
         "rel" : "collection",
         "href" : "http://localhost:8081/rest/projects/1/envs/1/actions",
         "methods" : [
            "get"
         ],
         "type" : "application/vnd.griddynamics.genesis.Action+json"
      },
      {
         "rel" : "collection",
         "href" : "http://localhost:8081/rest/projects/1/envs/1/workflows",
         "methods" : [
            "get"
         ],
         "type" : "application/vnd.griddynamics.genesis.Workflow+json"
      }
   ]
}

List of possible environment actions

Path: /rest/projects/(projectId)/envs/(environment id)/actions

Type: GET

Path parameters:

Parameter	Type	Description
projectId	Number	project id the env belong to
environment id	Number	Identifier of the environment

Example for broken environment

{
   "items" : [
      {
         "name" : "reset",
         "links" : [
            {
               "rel" : "self",
               "href" : "http://localhost:8081/rest/projects/1/envs/1/actions/reset",
               "methods" : [
                  "post"
               ],
               "type" : "application/vnd.griddynamics.genesis.Action+json"
            }
         ]
      }
   ],
   "links" : [
      {
         "rel" : "self",
         "href" : "http://localhost:8081/rest/projects/1/envs/1/actions",
         "methods" : [
            "get"
         ],
         "type" : "application/vnd.griddynamics.genesis.Action+json"
      }
   ]
}

Example for environment that runs workflow (status 'Busy')

{
   "items" : [
      {
         "name" : "cancel",
         "links" : [
            {
               "rel" : "self",
               "href" : "http://localhost:8081/rest/projects/1/envs/1/actions/cancel",
               "methods" : [
                  "post"
               ],
               "type" : "application/vnd.griddynamics.genesis.Action+json"
            }
         ]
      }
   ],
   "links" : [
      {
         "rel" : "self",
         "href" : "http://localhost:8081/rest/projects/1/envs/1/actions",
         "methods" : [
            "get"
         ],
         "type" : "application/vnd.griddynamics.genesis.Action+json"
      }
   ]
}

Run action

Path: /rest/projects/(projectId)/envs/(environment id)/actions/(action name)
Type: POST

Path parameters:

Parameter	Type	Description
projectId	Number	project id the env belong to
environment id	Number	Identifier of the environment
action name	String	Action name (see previous section)

Request body

None

Example results: see examples of common result object

Get workflows history

Path: /rest/projects/(projectId)/envs/(environment id)/history?page_offset=(number)&page_length=(number)
Type: GET

Path parameters:

Parameter	Type	Description
projectId	Number	project id the env belong to
environment id	Number	Identifier of the environment

Request parameters:

Parameter	Type	Description
page_offset	Number	number of the first record in a selection
page_length	Number	count of the records in a selection

Example results

{
    "history":[
        {
            "name":"destroy",
            "status":"Failed",
            "stepsCompleted":0.0,
            "steps":[
                {
                    "stepId":"52",
                    "phase":"destroy",
                    "status":"Failed",
                    "details":"Chef environment destruction"
                },
                {
                    "stepId":"53",
                    "phase":"destroy",
                    "status":"Succeed",
                    "details":"Environment destruction"
                }
            ],
            "executionStartedTimestamp":1341311242607
        },
        {
            "name":"create",
            "status":"Failed",
            "stepsCompleted":0.43,
            "steps":[
                {
                   "stepId":"41",
                   "phase":"provision",
                   "status":"Succeed",
                   "details":"Virtual machine(s) provisioning { quantity = 1, role = dbnode, image id = 45, hardware id = 3, ip address = unspecified, security group = unspecified, instance id = unspecified }"
                },
                {
                   "stepId":"42",
                   "phase":"provision",
                   "status":"Succeed",
                   "details":"Virtual machine(s) provisioning { quantity = 1, role = xwikinode, image id = 45, hardware id = 3, ip address = unspecified, security group = unspecified, instance id = unspecified }"
                },
                {
                   "stepId":"43",
                   "phase":"provision",
                   "status":"Succeed",
                   "details":"Virtual machine(s) provisioning { quantity = 1, role = lbnode, image id = 45, hardware id = 3, ip address = unspecified, security group = unspecified, instance id = unspecified }"
                },
                {
                   "stepId":"44",
                   "phase":"createdatabag",
                   "status":"Failed",
                   "details":"Chef databag creation { databag = xwiki }"
                },
                {
                   "stepId":"45",
                   "phase":"deploydb",
                   "status":"Requested",
                   "details":"Chef recipe execution { receipes = [ recipe[xwiki::db] ] }"
                },
                {
                   "stepId":"46",
                   "phase":"deployxwiki",
                   "status":"Requested",
                   "details":"Chef recipe execution { receipes = [ recipe[xwiki::app] ] }"
                },
                {
                   "stepId":"47",
                   "phase":"deploylb",
                   "status":"Requested",
                   "details":"Chef recipe execution { receipes = [ recipe[xwiki::lb] ] }"
                }
            ],
            "executionStartedTimestamp":1341310956532
        }
    ],
    "totalCount":2,
    "links" : [
      {
         "rel" : "self",
         "href" : "http://localhost:8081/rest/projects/1/envs/1/history",
         "methods" : [
            "get"
         ],
         "type" : "application/vnd.griddynamics.genesis.WorkflowHistory+json"
      }
   ]
}

Get list of possible environment workflows

Path: /rest/projects/(projectId)/envs/(environment id)/workflows

Type: GET

Path parameters:

Parameter	Type	Description
projectId	Number	project id the env belong to
environment id	Number	Identifier of the environment

Example result

{
   "items" : [
      {
         "name" : "destroy",
         "variables" : [],
         "links" : [
            {
               "rel" : "self",
               "href" : "http://localhost:8081/rest/projects/1/envs/1/workflows/destroy",
               "methods" : [
                  "post"
               ],
               "type" : "application/vnd.griddynamics.genesis.Workflow+json"
            }
         ]
      }
   ],
   "links" : [
      {
         "rel" : "self",
         "href" : "http://localhost:8081/rest/projects/1/envs/1/workflows",
         "methods" : [
            "get"
         ],
         "type" : "application/vnd.griddynamics.genesis.Workflow+json"
      }
   ]
}

Set new time to live (time period before automatic destruction) for environment

Path: /rest/projects/(projectId)/envs/(environment id)/timeToLive
Type: PUT

Path parameters:

Parameter	Type	Description
projectId	Number	project id the env belong to
environment id	Number	Identifier of the environment

Request body structure

Request body consists form a single JSON object that contains single key with predefined value:

Entry name	Type	Description
value	Number	New time to live value in minutes

Example request

{
  "value": 5
}

Remove time to live restrictions (time frame before automatic destruction) from environment

Path: /rest/projects/(projectId)/envs/(environment id)/timeToLive
Method Type: DELETE

Path parameters:

Parameter	Type	Description
projectId	Number	project id the env belong to
environment id	Number	Identifier of the environment