Unsupported content This version of the documentation is no longer supported. However, the documentation is available for your convenience. You will not be able to leave comments.

REST plans

Plans are high-level representations of the deployment scheduling, resource demands, and stage gateways (development, quality assurance, production, and cloud, for example) required to deploy an application or the related suite of applications.

GET /v1/plans

Returns all the plans.

Filters

  • aasm_state — String value for state machine
  • app_id — Integer id for a related application
  • environment_id — Integer id for a related environment
  • foreign_id — String value for foreign ID from external ticketing system responsible for creating the request
  • name — String for the plan name
  • plan_template_id — Integer value for the plan template ID
  • plan_type — String value for the plan type
  • project_server_id — Integer value for the integration or project server responsible for creating the request (for example, BMC Remedy)
  • release_date — String value for the release date
  • release_id — Integer value for the release ID
  • release_manager_id — Integer value for the user ID assigned as release manager
  • stage_id — Integer value for the stage included in the plan
  • team_id — Integer value for the team assigned to the plan

Common attributes

  • format — Ensure to include an accept header or add .xml or .json to the last path element
  • token — Your API Token for authentication

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid
  • ERROR 404 Not Found — Occurs when no records are found

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -X GET http://[rails_host]/v1/plans?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/plans?token=[api_token]

An example of filters:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "name":"Sample Plan" } }' http://[rails_host]/v1/plans?token=[api_token]

GET /v1/plans/[id]

Returns a plan by the ID.

Common attributes

  • id — Numerical unique ID for record
  • format — Ensure to include an accept header or add .xml or .json to the last path element
  • token — Your API Token for authentication

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid.
  • ERROR 404 Not found — Occurs when record to show is not found.

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -X GET http://[rails_host]/v1/plans/[id]?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/plans/[id]?token=[api_token]

POST /v1/plans

Creates a new plan from the posted data.

Required attributes

  • name — String name of the plan (unique)
  • plan_template_id — Integer value of an existing plan template ID (required if plan_template_name lookup not used)
  • plan_template_name — Triggers a lookup for an existing plan template by that name or return an error if not found

Optional attributes

  • release_id — Integer value of an existing release ID
  • release_name — Triggers a look up for an existing release by that name or return an error if not found
  • release_manager_id — Integer ID of the associated user assigned as release manager
  • release_date — String date for the release date
  • description — String for descriptive text
  • team_ids — Array of integer IDs for associated teams
  • release_attributes — Nested attributes for updating or creating an associated release (properties include 'name')

Common attributes

  • format — Ensure to include an accept header or add .xml or .json to the last path element
  • token — Your API Token for authentication

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid.
  • ERROR 422 Unprocessable entity — Occurs when validation fails and objects and errors are returned

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -H "Content-type: text/xml" -X POST -d '<plan><name>Sample Plan</name><release_name>Sample Release</release_name><plan_template_name>Sample Deploy Template</plan_template_name></plan>' http://[rails_host]/v1/plans?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{ "plan": { "name":"Sample Plan", "plan_template_name":"Sample Deploy Template", "release_name":"Sample Release" }' http://[rails_host]/v1/plans/?token=[api_token]

PUT /v1/plans/[id]

Updates an existing plan with values from a posted document.

Editable attributes

  • name — String name of the plan (unique)
  • plan_template_id — Integer value of an existing plan template ID (required if plan_template_name lookup not used)
  • plan_template_name — Triggers a lookup for an existing plan template by that name or return an error if not found
  • release_id — Integer value of an existing release ID 
  • release_name — Triggers a look up for an existing release by that name or return an error if not found
  • release_manager_id — Integer ID of the associated user assigned as release manager
  • release_date — String date for the release date
  • description — String for descriptive text
  • team_ids — Array of integer IDs for associated teams
  • release_attributes — Nested attributes for updating or creating an associated releases

State machine events

  • aasm_event — Can be submitted to transition a plan to the next state. Supported events: plan, start, lock, finish, archive, put_on_hold, cancel, delete

Common attributes

  • format — Ensure to include an accept header or add .xml or .json to the last path element
  • token — Your API Token for authentication

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid
  • ERROR 404 Not found — Occurs when record to update is not found
  • ERROR 422 Unprocessable entity — Occurs when validation fails and objects and errors are returned

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -H "Content-type: text/xml" -X PUT -d '<plan><name>Renamed Plan</name></plan>' http://[rails_host]/v1/plans/[id]?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "plan": { "name" : "Renamed Plan"}}'  http://[rails_host]/v1/plans/[id]?token=[api_token]

An example of starting a plan using the state machine:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "plan": { "aasm_event":"start" }}' http://[rails_host]/v1/plans/[id]?token=[api_token]

DELETE /v1/plans/[id]

Deletes a plan.

Common attributes

  • id — Numerical unique ID for record
  • format — Ensure to include an accept header or add .xml or .json to the last path element
  • token — Your API Token for authentication

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid
  • ERROR 404 Not found — Occurs when no records are found

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -X DELETE http://[rails_host]/v1/plans/[id]?token=[api_token]
curl -i -H "accept: application/json" -X DELETE http://[rails_host]/v1/plans/[id]?token=[api_token]

Sample output

The following JSON is a sample output from GET /v1/plans:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "2e24fb178af1a4fe55e2194932a12fd8"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 2288c97edb673d301e6cb1a7bea0c224
X-Runtime: 0.130000
Content-Type: application/json;charset=utf-8
Content-Length: 481
Date: Tue, 23 Oct 2012 23:52:52 GMT

[{
"aasm_state": "created",
"created_at": "2012-10-23T19:52:41-04:00",
"description": null,
"foreign_id": null,
"id": 1,
"name": "Sample Plan",
"plan_template_id": 1,
"project_server_id": null,
"release_date": "2012-10-31",
"release_id": null,
"release_manager_id": 1,
"updated_at": "2012-10-23T19:52:41-04:00",
"plan_template": {
"id": 1,
"is_automatic": false,
"name": "Sample Deploy Template",
"stages": [{
"id": 1,
"name": "Dev"
}, {
"id": 2,
"name": "QA"
}, {
"id": 3,
"name": "Prod"
}]
},
"teams": [{
"id": 1,
"name": "AllAccess"
}]
"plan_routes": [{
       "id":1,
       "route": {
           "description":"This is production route",
           "id":2,
           "name":"Production Route",
           "route_type":"open"
        }
    }],
   "plan_stage_instances": [{
       "aasm_state":"compliant",
       "id":3,
       "plan_stage": {
           "id":3,
           "name":"Prod"
        }
    },{
       "aasm_state":"compliant",
       "id":2,
       "plan_stage": {
           "id":2,
           "name":"QA"
        }
    },{
       "aasm_state":"compliant",
       "id":1,
       "plan_stage": {
           "id":1,
           "name":"Dev"
        }
    }]
}]

The following XML is a sample output from GET /v1/plans/1:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "0838d0182c45e75437e4a5c40a2f5598"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 183e5d8b40e2d5e1b6008050cbb1750f
X-Runtime: 0.199000
Content-Type: application/xml;charset=utf-8
Content-Length: 3883
Date: Tue, 23 Oct 2012 23:53:48 GMT

<?xml version="1.0" encoding="UTF-8"?>
<plan>
 <aasm-state>created</aasm-state>
 <created-at type="datetime">2012-10-23T19:52:41-04:00</created-at>
 <description nil="true"></description>
 <foreign-id nil="true"></foreign-id>
 <id type="integer">1</id>
 <name>Sample Plan</name>
 <plan-template-id type="integer">1</plan-template-id>
 <project-server-id type="integer" nil="true"></project-server-id>
 <release-date type="date">2012-10-31</release-date>
 <release-id type="integer" nil="true"></release-id>
 <release-manager-id type="integer">1</release-manager-id>
 <updated-at type="datetime">2012-10-23T19:52:41-04:00</updated-at>
 <plan-template>
   <archive-number nil="true"></archive-number>
   <archived-at type="datetime" nil="true"></archived-at>
   <created-at type="datetime">2012-10-23T19:50:52-04:00</created-at>
   <id type="integer">1</id>
   <is-automatic type="boolean">false</is-automatic>
   <name>Sample Deploy Template</name>
   <template-type>deploy</template-type>
   <updated-at type="datetime">2012-10-23T19:50:52-04:00</updated-at>
   <stages type="array">
     <stage type="PlanStage">
       <auto-start type="boolean">false</auto-start>
       <created-at type="datetime">2012-10-23T19:50:58-04:00</created-at>
       <id type="integer">1</id>
       <name>Dev</name>
       <plan-template-id type="integer">1</plan-template-id>
       <position type="integer">1</position>
       <requestor-access type="boolean">true</requestor-access>
       <updated-at type="datetime">2012-10-23T19:50:58-04:00</updated-at>
     </stage>
     <stage type="PlanStage">
       <auto-start type="boolean">false</auto-start>
       <created-at type="datetime">2012-10-23T19:51:05-04:00</created-at>
       <id type="integer">2</id>
       <name>QA</name>
       <plan-template-id type="integer">1</plan-template-id>
       <position type="integer">2</position>
       <requestor-access type="boolean">true</requestor-access>
       <updated-at type="datetime">2012-10-23T19:51:05-04:00</updated-at>
     </stage>
     <stage type="PlanStage">
       <auto-start type="boolean">false</auto-start>
       <created-at type="datetime">2012-10-23T19:51:11-04:00</created-at>
       <id type="integer">3</id>
       <name>Prod</name>
       <plan-template-id type="integer">1</plan-template-id>
       <position type="integer">3</position>
       <requestor-access type="boolean">true</requestor-access>
       <updated-at type="datetime">2012-10-23T19:51:11-04:00</updated-at>
     </stage>
   </stages>
 </plan-template>
 <teams type="array">
   <team>
     <id type="integer">1</id>
     <name>AllAccess</name>
   </team>
 </teams>
 <members type="array">
   <member type="PlanMember">
     <position type="integer">1</position>
     <stage>
       <id type="integer">1</id>
       <name>Dev</name>
       <position type="integer">1</position>
     </stage>
     <request>
       <aasm-state>created</aasm-state>
       <name>Sample Request</name>
       <number type="integer">1003</number>
     </request>
   </member>
   <member type="PlanMember">
     <position type="integer">2</position>
     <stage>
       <id type="integer">2</id>
       <name>QA</name>
       <position type="integer">2</position>
     </stage>
     <request>
       <aasm-state>created</aasm-state>
       <name>Sample Request</name>
       <number type="integer">1004</number>
     </request>
   </member>
   <member type="PlanMember">
     <position type="integer">3</position>
     <stage>
       <id type="integer">3</id>
       <name>Prod</name>
       <position type="integer">3</position>
     </stage>
     <request>
       <aasm-state>created</aasm-state>
       <name>Sample Request</name>
       <number type="integer">1005</number>
     </request>
   </member>
 </members>
 <plan-routes type="array">
   <plan-route>
     <id type="integer">1</id>
     <route>
       <description>This is production route</description>
       <id type="integer">2</id>
       <name>Production Route</name>      
<route-type>open</route-type>
     </route>
   </plan-route>
 </plan-routes>
 <plan-stage-instances type="array">
   <plan-stage-instance>     
 <aasm-state>compliant</aasm-state>
     <id type="integer">3</id>
     <plan-stage>
       <id type="integer">3</id>
       <name>Prod</name>
     </plan-stage>
   </plan-stage-instance>
   <plan-stage-instance>     
 <aasm-state>compliant</aasm-state>
     <id type="integer">2</id>
     <plan-stage>
       <id type="integer">2</id>
       <name>QA</name>
     </plan-stage>
   </plan-stage-instance>
   <plan-stage-instance>
     <aasm-state>compliant</aasm-state>
     <id type="integer">1</id>
     <plan-stage>
       <id type="integer">1</id>
       <name>Dev</name>
     </plan-stage>
   </plan-stage-instance>
 </plan-stage-instances>
</plan>

Related topic

REST-API-commands

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*