REST project servers

Project servers define the integration parameters (URL, user name, and password) for external ticketing or automation resources.

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/project_servers

Returns all project servers

Filters

  • name — String for project_servers name
  • active — Boolean value to show active project_servers (default is to show only active project_servers)
  • inactive — Boolean value to show inactive project_servers
  • 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

project_servers

queries, projects,
parent_projects,
releases, tickets

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

Filter examples:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "name":"Sample Project Server" } }' http://[rails_host]/v1/project_servers?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "include_except":"projects,releases,tickets" }}'  https://[rails_host]/v1/project_servers?token=[api_token]

GET /v1/project_servers/[id]

Returns a project_server 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

Errors caused

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

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

project_servers

queries, projects,
parent_projects,
releases, tickets

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

Filter example:

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

POST /v1/project_servers

Creates a new project server.

Required attributes

  • name — String name of the project server
  • server_name_id — Unique integer ID for identifying the project server type:
    • 1 = Rally
    • 2 = Jira
    • 3 = Mantis
    • 4 = ServiceNow
    • 5 = Hudson
    • 6 = SSH
    • 7 = Streamstep
  • server_url — String URL of the server
  • username — String user name for the project server

Optional attributes

  • details — String description of the project server
  • ip — String IP address for the project server
  • password — String password for the project server
  • port — Integer port number for the project server (optional except for Jira server name ID 2)
  • project_ids — Array of integer IDs for related projects
  • query_ids — Array of integer IDs for related queries
  • release_ids — Array of integer IDs for releases
  • ticket_ids — Array of integer IDs for tickets

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

project_servers

queries, projects,
parent_projects,
releases, tickets


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 '<project_server><name>Sample Project Server</name><server_name_id>1</server_name_id><server_url> http://www.example.com </server_url><username>admin</username></project_server>' http://[rails_host]/v1/project_servers?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json"  -X POST -d '{"project_server": {"name":"Sample Project Server", "server_name_id":1, "server_url":"http://www.example.com", "username":"admin" }}' http://[rails_host]/v1/project_servers/?token=[api_token]

Filter example:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{ "project_server": { "name" : "Rest Integration 1", "server_name_id":1, "server_url":"http://www.example.com", "username":"admin"}, "filters": {"include_except" : "projects,releases,tickets"}}' https://[rails_host]/v1/project_servers/?token=[api_token]

PUT /v1/project_servers/[id]

Updates an existing project_server with values from a posted document.

Editable attributes

  • details — String description of the project server
  • ip — String IP address for the project server
  • name — String name of the project server
  • password — String password for the project server
  • port — Integer port number for the project server (optional except for Jira server name ID 2)
  • project_ids — Array of integer IDs for related projects
  • query_ids — Array of integer IDs for related queries
  • release_ids — Array of integer IDs for releases
  • server_name_id— Integer identifying the project server type:
    • 1 = Rally
    • 2 = Jira
    • 3 = Mantis
    • 4 = ServiceNow
    • 5 = Hudson
    • 6 = SSH
    • 7 = Streamstep
  • server_url — String URL of the server (required)
  • ticket_ids — Array of integer IDs for tickets
  • username — String username for the project server

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

project_servers

queries, projects,
parent_projects,
releases, tickets

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 '<project_server><name>Renamed Project Server</name></project_server>' http://[rails_host]/v1/project_servers/[id]?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "project_server": { "name" : "Renamed Project Server"}}'  http://[rails_host]/v1/project_servers/[id]?token=[api_token]

Filter example:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "project_server": { "name" : "Renamed Integration 1"}, "filters": { "include_except":"projects,releases,tickets" }}' https://[rails_host]/v1/project_servers/[id]?token=[api_token]

DELETE /v1/project_servers/[id] 

Makes a project server inactive. Sets the active parameter for the project server to false.

Common attributes

  • id — Unique numerical ID for the project server 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/project_servers/[id]?token=[api_token]
curl -i -H "accept: application/json" -X DELETE http://[rails_host]/v1/project_servers/[id]?token=[api_token]

Sample output

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

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "105cafdd20b6862b8044237792553958"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 7fe2e0e5d262ad9a524b08fdce339226
X-Runtime: 0.112000
Content-Type: application/json;charset=utf-8
Content-Length: 431
Date: Wed, 24 Oct 2012 13:30:04 GMT

[{
"details": null,
"id": 1,
"ip": null,
"name": "Sample Project Server",
"port": null,
"server_name_id": 1,
"server_url": "http://www.example.com",
"username": "admin",
"projects": [],
"parent_projects": [],
"releases": [],
"tickets": []
}]

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

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "2f85278391473b3be5d112e2b0df8a84"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 8777b7675ad6aa1c460bbcf0aa9aa62c
X-Runtime: 0.165000
Content-Type: application/xml;charset=utf-8
Content-Length: 1031
Date: Wed, 24 Oct 2012 13:28:57 GMT

<?xml version="1.0" encoding="UTF-8"?>
<project-servers type="array">
 <project-server>
   <details nil="true"></details>
   <id type="integer">2</id>
   <ip nil="true"></ip>
   <name>Sample Project Server</name>
   <port type="integer" nil="true"></port>
   <server-name-id type="integer">1</server-name-id>
   <server-url>http://www.example.com</server-url>
   <username>admin</username>
   <projects type="array"/>
   <parent-projects type="array"/>
   <releases type="array"/>
   <tickets type="array"/>
 </project-server>
</project-servers>

Related topic

Integrating-servers

 

 

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