REST version tags

Version tags are controlled vocabularies for installed components that manage the range of valid versions that can be assigned in a step. These values can be manually entered in the metadata interface or added programmatically by an external repository system.

GET /v1/version_tags

Makes a version tag archived. Assigns the archive_number value and archived_at timestamp for the version tag.

Filters

• name — string for version tag name
• app_name — string for the application name
• component_name — string for the component name
• environment_name — string for the environment name
• archived — boolean for showing archived version tags (can be combined with unarchived version tags to show both)
• unarchived — boolean for showing unarchived version tags (on by default, can be combined with archived version tags to show both)

Common attributes

• format — be sure 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/version_tags?token=[api_token]

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

An example of filters:

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

GET /v1/version_tags/[id]

Returns a version_tag by the ID.

Common attributes

• id — numerical unique ID for record
• format — be sure 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 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/version_tags/[id]?token=[api_token]

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

POST /v1/version_tags

Creates a new version tag from the posted data.

Required attributes

• name — string name (required)

• special finders — as version tags can be associated with installed components or application environments, alsways use special finders to change the appropriate version tag

Special finders

Version tags can be associated with an installed component or with an application environment, but not with both  installed component and application environment at the same time. To associate a version tag with an installed component, use all three finders: application, component, and environment. To associate a version tag with an application environment, use only application and environment finders.

• find_application — lookup finder for application name that defines the application that the target installed component or application environment is associated with
• find_component — lookup finder for the component name that defines the installed component in the application requested in find_application
• find_environment — lookup finder for the environment name that is associated with the application requested in find_application

Optional attributes

• artifact_url — string url for the artifact

• installed_component_id — installed component ID (also set by find_application and find_component set together)

• properties (Starting with BRPM version 4.3.01.03 and later) — name and value of properties with which the version tags are extended

• active — boolean for the active/inactive state (defaults to true)

Common attributes

• format — be sure 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, 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 '<version_tag><name>REST Version Tag</name><find_application>SmartRelease</find_application><find_component>SS_Apache</find_component><find_environment>aws_cloud</find_environment></version_tag>' http://[rails_host]/v1/version_tags?token=[api_token]

curl -i -H "accept: application/json" -H "Content-type: application/json"  -X POST -d '{"version_tag": {"name":"1.0.1", "find_application":"SmartRelease", "find_component":"SS_Apache", "find_environment":"aws_cloud"}}' http://[rails_host]/v1/version_tags/?token=[api_token]

Here is an example of creation of the version tag with the extended properties:

curl -i -H "accept: text/xml" -H "Content-type: text/xml" -X POST -d '<version_tag><name>REST Version Tag</name><find_application>SmartRelease</find_application><find_component>SS_Apache</find_component><find_environment>aws_cloud</find_environment><properties><property><name>some_property_name1</name><value>some_property_value1</value></property></properties></version_tag>' http://[rails_host]/v1/version_tags?token=[api_token]

PUT /v1/version_tags/[id]

Updates an existing version tag with values from a posted document.

As version tags can be associated with installed components or application environments, alsways use special finders to change the appropriate version tag

Special finders

Version tags can be associated with an installed component or with an application environment, but not with both  installed component and application environment at the same time. To associate a version tag with an installed component, use all three finders: application, component, and environment. To associate a version tag with an application environment, use only application and environment finders.

• find_application — lookup finder for application name that defines the application that the target installed component or application environment is associated with
• find_component — lookup finder for the component name that defines the installed component in the application requested in find_application
• find_environment — lookup finder for the environment name that is associated with the application requested in find_application

Editable attributes

• name — string name
• app_id — integer ID of the app (alternative to find_application)
• artifact_url — string url for the artifact
• app_env_id — application environment ID (also set by find_application and find_environment set together)
• installed_component_id — installed component ID (also set by find_application and find_component set together)

• properties (Starting with BRPM version 4.3.01.03 and later) — name and value of properties with which the version tags are extended.

  Note

  If the version tag already includes the property, only the property value is changed.

• active - boolean for the active/inactive state (defaults to true)

   

Common attributes

• format — be sure 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, 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 '<version_tag><name>1.0.1_EDITED</name><find_application>SmartRelease</find_application><find_component>SS_Apache</find_component><find_environment>aws_cloud</find_environment></version_tag>' http://[rails_host]/v1/version_tags/[id]?token=[api_token]

curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT d '{"version_tag":
{"name":"1.0.1_EDITED", "find_application":"SmartRelease", "find_component":"SS_Apache", "find_environment":"aws_cloud"}}'  http://[rails_host]/v1/version_tags/[id]?token=[api_token]

Here is an example of editing of the version tag with the extended properties:

curl -i -H "accept: text/xml" -H "Content-type: text/xml" -X POST -d '<version_tag><name>REST Version Tag</name><find_application>SmartRelease</find_application><find_component>SS_Apache</find_component><find_environment>aws_cloud</find_environment><properties><property><name>some_property_name1</name><value>new_property_value1</value></property><property><name>some_property_name2</name><value>some_property_value2</value></property></properties></version_tag>' http://[rails_host]/v1/version_tags?token=[api_token]

DELETE /v1/version_tags/[id] 

Deletes a version tag.

Common attributes

• id — numerical unique ID for record
• format — be sure 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/version_tags/[id]?token=[api_token]

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

Sample output

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

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "1fd20ac63d3ffd37c8b51bd9697a20dc"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: f0b4593e55e89fc4e74e8c348c3765cb
X-Runtime: 0.128000
Content-Type: application/json;charset=utf-8
Content-Length: 259
Date: Thu, 30 Aug 2012 19:25:25 GMT

[{
	"app_id": 1,
    "archive_number": null,
    "archived_at": null,
	"artifact_url": null,
	"created_at": "2012-08-30T14:48:33-04:00",
	"id": 1,
	"installed_component_id": 3,
	"name": "1.0.1",
	"updated_at": "2012-08-30T14:48:33-04:00",
	"application_name": "SmartRelease",
	"component_name": "SS_Apache",
	"environment_name": "aws_cloud"
}]

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

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "820c15c8c50d67936f527f762994e3de"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 7d972b7c34785eabfef59e0d20079f7b
X-Runtime: 0.162000
Content-Type: application/xml;charset=utf-8
Content-Length: 548
Date: Thu, 30 Aug 2012 19:26:52 GMT

<?xml version="1.0" encoding="UTF-8"?>
<version-tag>
  <app-id type="integer">1</app-id>
  <archive-number nil="true"></archive-number>
  <archived-at type="datetime" nil="true"></archived-at>
  <artifact-url nil="true"></artifact-url>
  <created-at type="datetime">2012-08-30T14:48:33-04:00</created-at>
  <id type="integer">1</id>
  <installed-component-id type="integer">3</installed-component-id>
  <name>1.0.1</name>
  <updated-at type="datetime">2012-08-30T14:48:33-04:00</updated-at>
  <application-name>SmartRelease</application-name>
  <component-name>SS_Apache</component-name>
  <environment-name>aws_cloud</environment-name>
</version-tag>

Related topics

Setting up miscellaneous metadata