Skip to Content
Information
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 routes

GET /v1/routes

Returns all the routes (unarchived by default).

Filters

  • name — String for route name
  • app_id – Integer for application ID
  • route_type — String for route type (can be one of the follow values ‘open’, ‘mixed’ or ‘strict’)
  • archived — Boolean value for showing archived (can be combined with unarchived to show both)
  • unarchived — Boolean value for showing unarchived (on by default, can be combined with archived to show both)

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 — 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/routes?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/routes?token=[api_token]

An example of filters:

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

GET /v1/routes/[id]

Returns an route by the ID.

Common attributes

  • id — Numerical unique ID for the route
  • 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 — When the token is invalid
  • ERROR 404 Not found — When the record 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/routes/[id]?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/routes/[id]?token=[api_token]

POST /v1/routes

Creates a new route from the posted data.

Required attributes

  • name — String name of the route (required)
  • app_id — Integer ID of application

Optional attributes

  • description — String description of the route
  • route_type — String for route type (can be one of the follow values ‘open’, ‘mixed’ or ‘strict’. Default value is ‘open’)
  • route_gate_ids — Array of integer IDs for related route gates
  • plan_route_ids — Array of integer IDs for related plan routes

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 — When the token is invalid
  • ERROR 422 Unprocessable entity — When validation fails and objects and errors are returned
  • ERROR 500 Internal Server Error —  When server error occurred 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 '<route><name>Testing</name><app_id>1</app_id></route>' http://[rails_host]/v1/routes?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{"route": {"name":"Testing", "app_id":1 }}' http://[rails_host]/v1/routes/?token=[api_token]

PUT /v1/routes/[id]

Updates an existing route with values from the posted document.

Editable attributes

  • name — String name of the route
  • app_id — Integer id of application
  • description — String description of the route
  • route_type — String for route type (can be one of the follow values ‘open’, ‘mixed’ or ‘strict’. Default value is ‘open’)
  • route_gate_ids — Array of integer IDs for related route gates
  • plan_route_ids — Array of integer IDs for related plan routes

Toggle archival status

  • toggle_archive — Boolean value that toggles the archive status of an object.

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 — 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
  • ERROR 500 Internal Server Error — When server error occurred 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 '<route><name>Testing</name></route>' http://[rails_host]/v1/routes/[id]?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "route": { "name" : "Testing"}}' http://[rails_host]/v1/routes/[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/routes/[id]?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "toggle_archive": true }' http://[rails_host]/v1/routes/[id]?token=[api_token]

DELETE /v1/routes/[id]

Deletes a route.

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 — 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/routes/[id]?token=[api_token]
curl -i -H "accept: application/json" -X DELETE http://[rails_host]/v1/routes/[id]?token=[api_token]

Sample output

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

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "ec0515eb2dbde516221f5c3f81d46c85"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 3722c80dd7ed40cd1058611833e659a4
X-Runtime: 1.575000
Content-Type: application/json;charset=utf-8
Content-Length: 678
Date: Tue, 27 Aug 2013 14:53:55 GMT

[{
"archive_number":null,
"archived_at":null,
"created_at":"2013-08-23T10:44:52-04:00",
"description":"This is production route",
"id":2,
"name":"Production Route",
"route_type":"open",
"updated_at":"2013-08-23T10:44:52-04:00",
"app": {
"id":1,
"name":"SmartRelease"
},
"route_gates": [{
"different_level_from_previous":true,
"id":2,
"position":1,
"environment": {
"id":1,
"name":"aws_cloud"
}
}, {
"different_level_from_previous":true,
"id":3,
"position":2,
"environment": {
"id":2,
"name":"production"
}
}],
"plan_routes": [{
"id":1,
"plan": {
"id":1,
"name":"Plan #1"
}
}]
}]

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

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "eb842d55db10e464f6a376694e667d25"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 4d5ced5e5d6b65e930529eb8e86cc9fc
X-Runtime: 0.882000
Content-Type: application/xml;charset=utf-8
Content-Length: 1427
Date: Tue, 27 Aug 2013 14:57:05 GMT

<?xml version="1.0" encoding="UTF-8"?>
<route>
 <archive-number nil="true"></archive-number>
 <archived-at type="datetime" nil="true"></archived-at>
 <created-at type="datetime">2013-08-23T10:44:52-04:00</created-at>
 <description>This is production route</description>
 <id type="integer">2</id>
 <name>Production Route</name>
 <route-type>open</route-type>
 <updated-at type="datetime">2013-08-23T10:44:52-04:00</updated-at>
 <app>
   <id type="integer">1</id>
   <name>SmartRelease</name>
 </app>
 <route-gates type="array">
   <route-gate>
     <different-level-from-previous type="boolean">true</different-level-from-previous>
     <id type="integer">2</id>
     <position type="integer">1</position>
     <environment>
       <id type="integer">1</id>
       <name>aws_cloud</name>
     </environment>
   </route-gate>
   <route-gate>
     <different-level-from-previous type="boolean">true</different-level-from-previous>
     <id type="integer">3</id>
     <position type="integer">2</position>
     <environment>
       <id type="integer">2</id>
       <name>production</name>
     </environment>
   </route-gate>
 </route-gates>
 <plan-routes type="array">
   <plan-route>
     <id type="integer">1</id>
     <plan>
       <id type="integer">1</id>
       <name>Plan #1</name>
     </plan>
   </plan-route>
 </plan-routes>
</route>

Related topic

Managing-routes

 

 

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

BMC Release Process Management 4.6