Skip to Content

REST list items

List items are used with their parent list for maintaining various list_items options inside BMC Release Process Management. System list items are installed by default and cannot be archived or deleted.

Warning

Note

  • List items and their parent list can be used to store arbitrary user dictionaries of information, but their primary purpose is to support required configuration lists and enable those items to be customized within narrow boundaries. Parent lists that are required by the interface have protection from archiving and deleting but should be handled with care when updated through the REST API, because the user interface depends on the integrity of these list_items and their values.
  • 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/list_items

Returns all list items.

Filters

  • value_text — String for list_item value text
  • value_num — Integer value for list item value num
  • list_id — Integer ID for parent list ID
  • list_name — String for parent list name
  • 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)
  • 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

list_items

list

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

Example of filters:

curl -i -H "accept: application/json" -H "Content-type: application/json"  -X GET -d '{ "filters": { "list_name":"Sample List" }}' http://[rails_host]/v1/list_items?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -d '{ "filters": { "include_except":"list" }}' -X GET https://[rails_host]/v1/list_items?token=[api_token]

GET /v1/list_items/[id]

Returns a list item by 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

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

list_items

list


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

Filter example:

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

POST /v1/list_items

Creates a new list item from posted data.

Required Attributes

  • value_text — String name of the list_item (required if value_num is blank and parent list.is_text is true)
  • value_num — String name of the list_item (required if value_text is blank and parent list.is_text is false)

  • list_id — Integer of the parent list (required)

    Warning

    Note

    The parent List REST interface accepts nested attributes for list items, so you can create or edit a list and its list items in one request. Consider that as an alternative to individual calls to the list_item REST controller.

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

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. cx
  • 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

list_items

list

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 '<list_item><name>REST Process</name><app_ids>1</app_ids><app_ids>2</app_ids><label_color>#00FFFF</label_color></list_item>' http://[rails_host]/v1/list_items?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{"list_item": {"name":"Rest Process", "app_ids":[1,2], "label_color":"00FFFF" }}' http://[rails_host]/v1/list_items/?token=[api_token]

Filter example:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{ "list_item": { "value_text" : "Rest List Item 1", "list_id": 3}, "filters": {"include_except" : "list"}}' https://[rails_host]/v1/list_items/?token=[api_token]

PUT /v1/list_items/[id]

Updates an existing list item with values from a posted document.

Editable Attributes

  • value_text — String name of the list_item (required if value_num is blank and parent list.is_text is true)
  • value_num — String name of the list_item (required if value_text is blank and parent list.is_text is false)

  • list_id — Integer of the parent list (required)

    Warning

    Note

    The parent list REST interface accepts nested attributes for list items, so you can create or edit a list and its list items in one request. Consider that as an alternative to individual calls to the list_item REST controller.

  • name — String name of the list item (required)

Toggle Archival Status

  • toggle_archive — Boolean value that will toggle 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

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. cx
  • 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

list_items

list

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 '<list_item><value_text>Renamed List Item Value</value_text></list_item>' http://[rails_host]/v1/list_items/[id]?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "list_item": { "value_text" : "Renamed List Item Value"}}'  http://[rails_host]/v1/list_items/[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/list_items/[id]?token=[api_token]

Filter example:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "list_item": { "value_text" : "Renamed List Item 1" }, "filters": { "include_except":"list" }}' https://[rails_host]/v1/list_items/[id]?token=[api_token]

DELETE /v1/list_items/[id]

Deletes a list item.

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

Sample Output

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

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "45fc395380a559628a48a66e61b297c0"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 8d5508efe00975b2717eed48c1a09480
X-Runtime: 0.152000
Content-Type: application/json;charset=utf-8
Content-Length: 674
Date: Wed, 05 Sep 2012 18:52:52 GMT

[{
"archive_number": null,
"archived_at": null,
"created_at": "2012-09-05T13:53:25-04:00",
"created_by_id": 1,
"id": 26,
"is_text": true,
"name": "Sample List Item",
"updated_at": "2012-09-05T14:12:26-04:00",
"required?": false,
"list_item_items": [{
"archive_number": null,
"archived_at": null,
"created_at": "2012-09-05T13:53:25-04:00",
"id": 181,
"last_modified_by_id": null,
"updated_at": "2012-09-05T14:12:26-04:00",
"value_num": null,
"value_text": "Sample List Item Item 1"
}, {
"archive_number": null,
"archived_at": null,
"created_at": "2012-09-05T13:53:25-04:00",
"id": 182,
"last_modified_by_id": null,
"updated_at": "2012-09-05T14:12:26-04:00",
"value_num": null,
"value_text": "List Item Item 2"
}]
}]

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

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "9ea742c1727779538c4fc4bca1b5c259"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 2103b5e9df1d5773ea16d9bbfd9667c0
X-Runtime: 0.222000
Content-Type: application/xml;charset=utf-8
Content-Length: 6119
Date: Wed, 05 Sep 2012 15:38:46 GMT

<?xml version="1.0" encoding="UTF-8"?>
<list_item>
 <archive-number nil="true"></archive-number>
 <archived-at type="datetime" nil="true"></archived-at>
 <created-at type="datetime">2012-09-05T13:53:25-04:00</created-at>
 <created-by-id type="integer">1</created-by-id>
 <id type="integer">26</id>
 <is-text type="boolean">true</is-text>
 <name>Sample List Item Again</name>
 <updated-at type="datetime">2012-09-05T14:12:26-04:00</updated-at>
 <required? type="boolean">false</required?>
 <list_item-items type="array">
   <list_item-item>
     <archive-number nil="true"></archive-number>
     <archived-at type="datetime" nil="true"></archived-at>
     <created-at type="datetime">2012-09-05T13:53:25-04:00</created-at>
     <id type="integer">181</id>
     <last-modified-by-id type="integer" nil="true"></last-modified-by-id>
     <updated-at type="datetime">2012-09-05T14:12:26-04:00</updated-at>
     <value-num type="integer" nil="true"></value-num>
     <value-text>Sample List Item Item 1</value-text>
   </list_item-item>
   <list_item-item>
     <archive-number nil="true"></archive-number>
     <archived-at type="datetime" nil="true"></archived-at>
     <created-at type="datetime">2012-09-05T13:53:25-04:00</created-at>
     <id type="integer">182</id>
     <last-modified-by-id type="integer" nil="true"></last-modified-by-id>
     <updated-at type="datetime">2012-09-05T14:12:26-04:00</updated-at>
     <value-num type="integer" nil="true"></value-num>
     <value-text>Sample List Item Item 2</value-text>
   </list_item-item>
 </list_item-items>
</list_item>

Related topic

REST-API-version-1

 

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

BMC Release Process Management 5.0.07