Skip to Content

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.8