REST apps

Apps (short for applications) are the primary software objects in BMC Release Process Management. Apps have components that are installed in multiple environments and can be deployed through process models, such as plans and requests.

Note

The include_except and alone filters are available in only 5.0.03.004 and later versions of RPM. Use these filters to limit the data in API response and hence, reduce the API response time.

GET /v1/apps

Returns all the apps.

Filters

name—String value for the application name
active—Boolean value indicating active apps (default is to show only active apps)
inactive—Boolean value indicating inactive apps
include_except—Comma-separated strings of the top-level associated items to exclude from the response. You can remove only top-level associated items from the response and these associated items should be a collection (zero to many) of other objects (not a simple property—string, numeric, boolean, and so on). For example, you can remove components from an application but you cannot remove route gates (it is not a top-level associated item) or app_version (it is a simple property). If you provide an incorrect associated item name (for example, the associated item does not exist, is not at the top level, or is a property), the name is ignored. See the table below for the items and their associated items.
alone—Boolean value to return only the item or the associated items as well along with the item. If set to false (default), item and associated item details are returned; if set to true, only item details are returned. See the table below for the items and their associated items. See the table below for the items and their associated items.

Item	Associated items
apps	requests, steps, environments, components, installed_components, teams, users, tickets, routes

Tip

To find an application by name, you can use the full name or a short code prefix separated from the main name by a delimiter: |. If the application name is "BMC Release Process Management," a name with a short code might be "BRPM_|_Release Process Management." To find this application, the value for "name" could be either "BRPM" or "Release Process Management."

Common attributes

format—Accept header or .xml or .json added to the last path element
token—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, enter this URL or your valid API key and application host into a browser or HTTP client, such as wget or curl. For example:

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

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

Filter examples:

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

curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "include_except": "requests,steps,components" } }' https://[rails_host]/v1/apps?token=[api_token]

GET /v1/apps/[id]

Returns an app by the ID.

Filters

include_except—Comma-separated strings of the top-level associated items to exclude from the response. You can remove only top-level associated items from the response and these associated items should be a collection (zero to many) of other objects (not a simple property—string, numeric, boolean, and so on). For example, you can remove components from an application but you cannot remove route gates (it is not a top-level associated item) or app_version (it is a simple property). If you provide an incorrect associated item name (for example, the associated item does not exist, is not at the top level, or is a property), the name is ignored. See the table below for the items and their associated items.
alone—Boolean value to return only the item or the associated items as well along with the item. If set to false (default), item and associated item details are returned; if set to true, only item details are returned. See the table below for the items and their associated items. See the table below for the items and their associated items.

Item	Associated items
apps	requests, steps, environments, components, installed_components, teams, users, tickets, routes

Common attributes

id—Unique numerical ID for a record
export_app—Boolean value indicating an exported JSON or XML file
Warning
Notes
- The export_app attribute returns an export file in the format that you are currently using in the API, either JSON or XML. For example, if a JSON header is used to request the export file, a JSON export file is returned and likewise for XML. To export an application file using the export_app attribute requires BMC Release Process Management version 4.8.00.01 or later. The export_app attribute is the preferred method to use for both JSON and XML formats.
- BMC Release Process Management version 4.8.00.01 and later releases support exporting automation scripts of types Automation and Resource Automation.

export_xml—Boolean value indicating an exported XML file
Warning
Note
BMC Release Process Management version 4.8 supports only XML for export. Version 4.8.00.01 or later supports the export_xml attribute; however, regardless of the format that you are currently using in the API (either JSON or XML), the exported file is always in XML format. The preferred method to use is the export_app attribute.
optional_components—String value for the component name
Warning
Note
Valid component names are req_templates, servers, automations, and deployment_windows. The defaults for these are false unless explicitly passed through the optional_components attribute.
format—Accept header or .xml or .json added to the last path element
token—API token for authentication

Errors caused

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

Examples

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

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

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

The following examples show an export with no optional components:

curl -i -H "accept: text/xml" -X GET http://[rails_host]/v1/apps/[id]?token=[api_token]&export_app=true

curl -i -H "accept: text/xml" -X GET "http://[rails_host]/v1/apps/[id]?token=[api_token]&export_xml=true" > [application_name].xml

The following examples show an export with all optional components:

curl -i -H "accept: text/xml" -X GET http://[rails_host]/v1/apps/[id]?token=[api_token]&export_app=true&optional_components=[req_templates,servers,automations,deployment_windows]

curl -i -H "accept: application/json" -X GET "http://[rails_host]/v1/apps/[id]?token=[api_token]&export_app=true&optional_components=\[req_templates, servers, automations, deployment_windows\]" > [application_name].json

The following examples show an export with only servers as optional components:

curl -i -H "accept: text/xml" -X GET http://[rails_host]/v1/apps/[id]?token=[api_token]&export_app=true&optional_components=[servers]

curl -i -H "accept: application/json" -X GET "http://[rails_host]/v1/apps/[id]?token=[api_token]&export_app=true&optional_components=\[servers\]" > [application_name].json

Filter example:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "include_except": "requests,steps,components" } }' https://[rails_host]/v1/apps/[id]?token=[api_token]

POST /v1/apps

Creates a new app from a posted data.

Required attribute

name—Unique name (string) of the app
team_ids—Array of integer IDs for related teams

Optional attributes

active—Boolean value (default is true)
app_version—String that represents the application version
business_process_ids—Array of integer IDs for related business processes
component_ids—Array of integer IDs for related components
component_template_ids—Array of integer IDs for related component templates
default—Boolean value (default value is false)
description—String that describes the app
environment_ids—Array of integer IDs for related environments
installed_component_ids—Array of integer IDs for related installed components
package_template_ids—Array of integer IDs for related package templates
request_ids—Array of integer IDs for related requests
ticket_ids—Array of integer IDs for related tickets
user_ids—Array of integer IDs for related users

Common attributes

format—Accept header or .xml or .json added to the last path element
token—API token for authentication

Filters

include_except—Comma-separated strings of the top-level associated items to exclude from the response. You can remove only top-level associated items from the response and these associated items should be a collection (zero to many) of other objects (not a simple property—string, numeric, boolean, and so on). For example, you can remove components from an application but you cannot remove route gates (it is not a top-level associated item) or app_version (it is a simple property). If you provide an incorrect associated item name (for example, the associated item does not exist, is not at the top level, or is a property), the name is ignored. See the table below for the items and their associated items.
alone—Boolean value to return only the item or the associated items as well along with the item. If set to false (default), item and associated item details are returned; if set to true, only item details are returned. See the table below for the items and their associated items. See the table below for the items and their associated items.

Item	Associated items
apps	requests, steps, environments, components, installed_components, teams, users, tickets, routes

Importing files

app_import team=x—String that represents the team associated with the imported application
Warning
Note
In BMC Release Process Management version 4.8, the app_import tag is the parent of the exported XML file. Exported data is inside the <app> ... </app> tags and <app_import> tags surround that data.
In version 4.8.00.01 or later, the file type is determined automatically during the import operation for both the API and UI. However, you must specify the team for both API import formats. For example:
XML
<app_import team="[default]">
<app> … </app>
</app_import>
JSON
{ "app_import": {
"team": "[default]", “app”: {…}
}}
Warning
Note
BMC Release Process Management version 4.8.00.01 and later releases support importing automation scripts of types Automation and Resource Automation.

Errors caused

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

Examples

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

curl -i -H "accept: text/xml" -H "Content-type: text/xml" -X POST -d @[application_name].xml http://[rails_host]/v1/apps?token=[api_token]

curl -i -H "accept: text/xml" -H "Content-type: text/xml" -X POST -d '<app><name>REST App</name><team_ids>2</team_ids></app>' http://[rails_host]/v1/apps?token=[api_token]

curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{"app" : { "name":"Rest App" } }' http://[rails_host]/v1/apps/?token=[api_token]

curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{"app" : { "name":"Rest App","team_ids":2 } }' http://[rails_host]/v1/apps/?token=[api_token]

Filter example:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{"app" : { "name":"Rest App 1", "team_ids":0 }, "filters": {"include_except": "requests,steps,components"} }' https://[rails_host]/v1/apps/?token=[api_token]

The following example shows the app_import tag:

<app_import team="[default]">

<app>
   <a-sorting-comps type="boolean">false</a-sorting-comps>
   <a-sorting-envs type="boolean">false</a-sorting-envs>
   <active type="boolean">true</active>
   <app-version>0.0</app-version>
   <name>import_app_blank</name>
   <strict-plan-control type="boolean">false</strict-plan-control>
   <components type="array"/>
   <environments type="array"/>
   <active-packages type="array"/>
   <installed-components type="array"/>
   <active-routes type="array"/>
   <active-business-processes type="array"/>
   <version-tags type="array"/>
   <application-packages type="array"/>
   <requests-for-export type="array"/>
</app>
</app_import>

The following example shows a JSON application export with the team defined and ready for import:

{"app_import":{"team":"[default]”,
"app":
"a_sorting_comps":false,
"a_sorting_envs":false,
"active":true,
"app_version":"",
"name":"EmptyApp",
"strict_plan_control":false,
"components":[],
"environments":[],
"active_packages":[],
"installed_components":[],
"active_routes":[],
"active_business_processes":[],
"version_tags":[],
"application_packages":[],
"brpm_version":"4.8.00"}
}}

PUT /v1/apps/[id]

Updates an existing app with values from a posted document.

Editable attributes

active—Boolean value (Default is true.)
app_version—String that represents the application version
business_process_ids—Array of integer IDs for related business processes
component_ids—Array of integer IDs for related components
component_template_ids—Array of integer IDs for related component templates
default—Boolean value (Default value is false.)
description—String that describes the app
environment_ids—Array of integer IDs for related environments
installed_component_ids—Array of integer IDs for related installed components
name—Unique name (string) of the app
package_template_ids—Array of integer IDs for related package templates
request_ids—Array of integer IDs for related requests
team_ids—Array of integer IDs for related teams
ticket_ids—Array of integer IDs for related tickets
user_ids—Array of integer IDs for related users

Common attributes

format—Accept header or .xml or .json added to the last path element
token—API token for authentication

Filters

include_except—Comma-separated strings of the top-level associated items to exclude from the response. You can remove only top-level associated items from the response and these associated items should be a collection (zero to many) of other objects (not a simple property—string, numeric, boolean, and so on). For example, you can remove components from an application but you cannot remove route gates (it is not a top-level associated item) or app_version (it is a simple property). If you provide an incorrect associated item name (for example, the associated item does not exist, is not at the top level, or is a property), the name is ignored. See the table below for the items and their associated items.
alone—Boolean value to return only the item or the associated items as well along with the item. If set to false (default), item and associated item details are returned; if set to true, only item details are returned. See the table below for the items and their associated items. See the table below for the items and their associated items.

Item	Associated items
apps	requests, steps, environments, components, installed_components, teams, users, tickets, routes

Errors caused

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

Examples

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

curl -i -H "accept: text/xml" -H "Content-type: text/xml" -X PUT -d '<app><name>Renamed App</name></app>' http://[rails_host]/v1/apps/[id]?token=[api_token]

curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "app": { "name" : "Renamed App" } }' http://[rails_host]/v1/apps/[id]?token=[api_token]

Filter example:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "app": { "name" : "Renamed App 1" }, "filters": {"include_except": "requests,steps,components"} }' https://[rails_host]/v1/apps/[id]?token=[api_token]

DELETE /v1/apps/[id]

Makes an app inactive. Sets the active parameter for the app to false.

Common attributes

id—Unique numerical ID for a record
format—Accept header or .xml or . json added to the last path element
token—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

Sample output

The following JSON is sample output from GET /v1/apps:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "eeeb7bdbbb9f3cf4b0fa00e781e6fdd1"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 01f9fa0eeb3138f7920d30e7029849ad
X-Runtime: 1.759000
Content-Type: application/json;charset=utf-8
Content-Length: 6418
Date: Tue, 23 Oct 2012 13:33:59 GMT

[{
"active": true,
"app_version": "2.0.4",
"created_at": "2011-04-29T00:12:12-04:00",
"default": false,
"id": 1,
"name": "SR_|_SmartRelease",
"updated_at": "2012-09-06T08:11:35-04:00",
"requests": [{
"id": 35,
"name": "Request Example"
}],
"steps": [{
"id": 1,
"name": "Step 1"
}],
"environments": [{
"id": 1,
"name": "aws_cloud"
}, {
"id": 2,
"name": "production"
}],
"components": [{
"id": 1,
"name": "AppContainer"
}, {
"id": 2,
"name": "SS_Apache"
}, {
"id": 3,
"name": "SS_Passenger"
}, {
"id": 4,
"name": "SS_MySQL"
}, {
"id": 5,
"name": "SS_RailsApp"
}],
"installed_components": [{
"id": 7
}, {
"id": 8
}, {
"id": 9
}, {
"id": 10
}, {
"id": 1
}, {
"id": 2
}, {
"id": 5
}, {
"id": 6
}, {
"id": 3
}, {
"id": 4
}],
"teams": [],
"users": [{
"email": "admin@example.com",
"first_name": "John",
"id": 1,
"last_name": "Administrator",
"login": "admin"
}],
"tickets": []
"routes":[{
        "id":3,
        "name":"Another Production Route",
        "route_type":"open",
        "route_gates": [{
            "description":null,
            "id":5
        }]
    }, {
        "id":1,
        "name":"[default]",
        "route_type":"open",
        "route_gates": [{
            "description":null,
            "id":1
        },{
            "description":null,
            "id":4
        }]
    }]
}]

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

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "ba08d21ab2b9fd1b708f87104fb3394e"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: f03b6c4fe25ae6231d34ddf89579e1e9
X-Runtime: 0.857000
Content-Type: application/xml;charset=utf-8
Transfer-Encoding: chunked
Date: Tue, 23 Oct 2012 13:38:23 GMT

<app>
  <active type="boolean">true</active>
  <app-version>2.0.4</app-version>
  <created-at type="datetime">2011-04-29T00:12:12-04:00</created-at>
  <default type="boolean">false</default>
  <id type="integer">1</id>
  <name>SR_|_SmartRelease</name>
  <updated-at type="datetime">2012-09-06T08:11:35-04:00</updated-at>
  <requests type="array">
    <request>
      <id type="integer">1</id>
      <name nil="true"></name>
    </request>
  </requests>
  <steps type="array">
    <step>
      <id type="integer">1</id>
      <name>Step 1</name>
    </step>
  </steps>
  <environments type="array">
    <environment>
      <id type="integer">1</id>
      <name>aws_cloud</name>
    </environment>
    <environment>
      <id type="integer">2</id>
      <name>production</name>
    </environment>
  </environments>
  <components type="array">
    <component>
      <id type="integer">1</id>
      <name>AppContainer</name>
    </component>
    <component>
      <id type="integer">2</id>
      <name>SS_Apache</name>
    </component>
    <component>
      <id type="integer">3</id>
      <name>SS_Passenger</name>
    </component>
    <component>
      <id type="integer">4</id>
      <name>SS_MySQL</name>
    </component>
    <component>
      <id type="integer">5</id>
      <name>SS_RailsApp</name>
    </component>
  </components>
  <installed-components type="array">
    <installed-component>
      <id type="integer">7</id>
    </installed-component>
    <installed-component>
      <id type="integer">8</id>
    </installed-component>
    <installed-component>
      <id type="integer">9</id>
    </installed-component>
    <installed-component>
      <id type="integer">10</id>
    </installed-component>
    <installed-component>
      <id type="integer">1</id>
    </installed-component>
    <installed-component>
      <id type="integer">2</id>
    </installed-component>
    <installed-component>
      <id type="integer">5</id>
    </installed-component>
    <installed-component>
      <id type="integer">6</id>
    </installed-component>
    <installed-component>
      <id type="integer">3</id>
    </installed-component>
    <installed-component>
      <id type="integer">4</id>
    </installed-component>
  </installed-components>
  <teams type="array"/>
  <users type="array">
    <user>
      <email>admin@example.com</email>
      <first-name>John</first-name>
      <id type="integer">1</id>
      <last-name>Administrator</last-name>
      <login>admin</login>
    </user>
  </users>
  <tickets type="array"/>
  <routes type="array">
    <route>
      <id type="integer">3</id>
      <name>Another Production Route</name>
      <route-type>open</route-type>
      <route-gates type="array">
        <route-gate>
          <description nil="true"></description>
          <id type="integer">5</id>
        </route-gate>
      </route-gates>
    </route>
    <route>
      <id type="integer">1</id>
      <name>[default]</name>
      <route-type>open</route-type>
      <route-gates type="array">
        <route-gate>
          <description nil="true"></description>
          <id type="integer">1</id>
        </route-gate>
        <route-gate>
          <description nil="true"></description>
          <id type="integer">4</id>
        </route-gate>
      </route-gates>
    </route>
  </routes>
</app>

REST apps

GET /v1/apps

Filters

Common attributes

Errors caused

Examples

GET /v1/apps/[id]

Filters

Common attributes

Errors caused

Examples

POST /v1/apps

Required attribute

Optional attributes

Common attributes

Filters

Importing files

Errors caused

Examples

PUT /v1/apps/[id]

Editable attributes

Common attributes

Filters

Errors caused

Examples

DELETE /v1/apps/[id]

Common attributes

Errors caused

Sample output

BMC Release Process Management 5.0.07

On this page