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 request templates

Request templates are a companion model to requests that allow new requests to be created based on the structure and contents of an original request. When a request template is made in the user interface from an existing request, the request is first copied into a new invisible request. Then a request template model is added that refers to that source request and provides the methods needed for cloning the source request under various conditions.

The UI provides a rich interface for manipulating request templates. The REST interface for templates is currently mostly useful for retrieving a list of existing request templates and using the id from those request templates in other commands. Future versions of the API will support more advanced operations using the REST interface.

GET /v1/request_templates

Returns request templates that are not deleted nor archived.

Filters

  • name — String for the phase name
  • archived — Boolean value for showing the archived status (it can be combined with unarchived to show both)
  • unarchived — Boolean value for showing unarchived (on by default, it can be combined with unarchived to show both)
  • parent_id — Integer ID of the request template used to create a sibling or request template variant
  • environment_id — Integer ID of the environment to which the source request was originally associated
  • app_id — Integer ID of the application to which the source request was originally associated

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

Raises

  • ERROR 403 Forbidden — When the token is invalid
  • ERROR 404 Not Found — 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/request_templates?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/request_templates?token=[api_token]

Examples of filters:

curl -i -H "accept: application/json" -H "Content-type: application/json"  -X GET -d '{ "filters": { "name":"Sample Request Template" }}' http://[rails_host]/v1/request_templates?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json"  -X GET -d '{ "filters": { "completed_start_date":"01/01/2012", "completed_end_date":"12/01/2012" }}' http://[rails_host]/v1/request_templates?token=[api_token]

GET /v1/request_templates/[id]

Returns a request template by request template 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

Raises

  • ERROR 403 Forbidden — When the token is invalid
  • ERROR 404 Not found — 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/request_templates/[id]?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/request_templates/[id]?token=[api_token]

POST /v1/request_templates

Creates a new request template from posted data.

Required attributes

  • name — String value of the name of the request template
  • request_id_to_clone — Integer ID of an existing request to clone as the basis of this new request template

Optional attributes

  • team_id —Integer ID for the team associated with the request template

  • parent_id — Integer ID for the parent request ID from which this request template was created as a template

     

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

Raises

  • ERROR 403 Forbidden — When the token is invalid
  • ERROR 422 Unprocessable entity — 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 "<request_template><name>Rest Request Template</name> <request_id_to_clone>1</request_id_to_clone></request_template>" HTTP://[rails_host]/v1/request_templates?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{ "request_template": { "name" : "Rest Request Template 2", "request_id_to_clone" : 1} }' HTTP://[rails_host]/v1/request_templates/?token=[api_token]

PUT /v1/request_templates/[id]

Updates an existing request template with values from a posted document.

Editable attributes

  • name — String value of the name of the request template
  • team_id — Integer ID for the team associated with the request template

Toggle archival status

  • toggle_archive — Set value to string "true" to toggle the archive status of an object to and from archived and unarchived if the request template is not assigned to any plan templates through plan stages

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

Raises

  • ERROR 403 Forbidden — When the token is invalid
  • ERROR 404 Not found — When record to update is not found
  • ERROR 422 Unprocessable entity — 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 '<request_template><name>Renamed Request Template</name></request_template>' http://[rails_host]/v1/request_templates/[id]?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "request_template": { "name" : "Renamed Request Template"}}'  http://[rails_host]/v1/request_templates/[id]?token=[api_token]

An example toggling the archive status of an object:

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

DELETE /v1/request_templates/[id]

Deletes a request template

The request template must first be archived in order to be deleted.

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

Raises

  • ERROR 403 ForbIDden — When the token is invalid
  • ERROR 404 Not found — 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/request_templates/[id]?token=[api_token]
curl -i -H "accept: application/json" -X DELETE http://[rails_host]/v1/request_templates/[id]?token=[api_token]

Sample output

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

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "0505f2a9b34087878c0aa3d655dafb97"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: ef750c0abfb24a399d0d895d53e61c12
X-Runtime: 0.073000
Content-Type: application/json;charset=utf-8
Content-Length: 379
Date: Mon, 18 Mar 2013 13:57:46 GMT

[{
"archive_number": null,
"archived_at": null,
"created_at": "2013-03-18T09:52:49-04:00",
"id": 1,
"name": "Sample Request Template",
"parent_id": null,
"recur_time": null,
"team_id": null,
"updated_at": "2013-03-18T09:52:49-04:00",
"request": {
"aasm_state": "created",
"id": 2,
"name": "Sample Request"
},
"variants": [],
"plan_stages": [{
"id": 1,
"name": "Dev"
}, {
"id": 2,
"name": "UAT"
}, {
"id": 3,
"name": "Prod"
}]
}]

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

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "4d3e9549015b71a23574e8fd85035fb0"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 21a61b4b264facf6704399ba64e2298b
X-Runtime: 0.103000
Content-Type: application/xml;charset=utf-8
Content-Length: 1009
Date: Mon, 18 Mar 2013 14:01:12 GMT

<?xml version="1.0" encoding="UTF-8"?>
<request-template>
<archive-number nil="true"></archive-number>
<archived-at type="datetime" nil="true"></archived-at>
<created-at type="datetime">2013-03-18T09:52:49-04:00</created-at>
<id type="integer">1</id>
<name>Sample Request Template</name>
<parent-id type="integer" nil="true"></parent-id>
<recur-time type="integer" nil="true"></recur-time>
<team-id type="integer" nil="true"></team-id>
<updated-at type="datetime">2013-03-18T09:52:49-04:00</updated-at>
<request>
<aasm-state>created</aasm-state>
<id type="integer">2</id>
<name>Sample Request</name>
</request>
<variants type="array"/>
<plan-stages type="array">
<plan-stage>
<id type="integer">1</id>
<name>Dev</name>
</plan-stage>
<plan-stage>
<id type="integer">2</id>
<name>UAT</name>
</plan-stage>
<plan-stage>
<id type="integer">3</id>
<name>Prod</name>
</plan-stage>
</plan-stages>
</request-template>

Related topic

Managing-requests

 

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