WS API: How to query for workspace by name

Document ID : KB000057602
Last Modified Date : 14/02/2018
Show Technical Document Details

Resolution



Background:
Please see this article for examples of WS API GET and POST requests in a browser rest client or in a terminal using curl.

Authentication:
The preferred method of authentication for rally1.rallydev.com is ApiKey but this article is using username/password for authenticating GET requests. For information about ApiKey please see ApiKey FAQ.

Setup:
In the example below requests are made in a browser REST client. The user whose credentials are used to authenticate the requests has access to more than one workspace:

User-added image

This user's default workspace is NM Chicago. Queries for a non-default workspace will require an additional workspace parameter. Queries to a default workspace do not require a worspace parameter because they are implicitly scoped to the user's default workspace.

1. Construct an endpoint for a default workspce:

https://rally1.rallydev.com/slm/webservice/v2.0/workspace?query=(Name = "NM Chicago")

Use your REST client's interface to set username/password. Screenshots below are specific to Chrome's Advanced REST Client:

User-added image

User-added image

2. Make the request:

User-added image


3. Construct an endpoint for a non-default workspce:

If we construct this endpoint without the workspace parameter 0 results will be returned.
https://rally1.rallydev.com/slm/webservice/v2.0/workspace?query=(Name = "NMDS")
To make this endpoint work, the request must be scoped as shown below:

https://rally1.rallydev.com/slm/webservice/v2.0/workspace?query=(Name = "NMDS")&workspace=/workspace/12352608129

In this example 12352608129 is the ObjectID of the workspace.
See this article on how to find out ObjectID of a workspace.

User-added image

4. Endpoint to get all workspaces in the subscription.

Start with this endpoint to get the ObjectID of your subscription:

https://rally1.rallydev.com/slm/webservice/v2.0/subscription

In this example the ref property of the result looks like this:

"_ref":?"https://rally1.rallydev.com/slm/webservice/v2.0/subscription/1154643"

Next, we use the ObjectID of the subscription, 1154643 in this example, to construct this endpoint:

The total result count of this query will vary depending on the permissions of the user who is authenticating the request. Since this user has access to 4 workspaces only, the total result count is 4. A different user may have a different total result count. A subscription administrator will get all workspaces in the subscription:

https://rally1.rallydev.com/slm/webservice/v2.0/Subscription/1154643/Workspaces

User-added image

For more details see this article on how to get ObjectIDs of all workspaces in the subscription.