Skip to content

REST: Environments related API

Jump to bottom Edit New page
Svyatoslav Reyentenko edited this page Feb 5, 2013 · 29 revisions

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
Add a custom footer
Add a custom sidebar
Clone this wiki locally