Agile Central - WSAPI: Not finding workspaces when querying the Workspace endpoint.

Document ID : KB000118587
Last Modified Date : 26/10/2018
Show Technical Document Details
Question:
I am a Subscription Admin. I'm using my Full Access api-key, but not getting results when querying for workspaces.

Here is an example:
https://rally1.rallydev.com/slm/webservice/v2.0/workspace?query=(Name = "MyWorkspaceName")&fetch=true&start=1&pagesize=20 

This returns no results. Even if I encode the query argument so that it's (Name%20%3D%20%22MyWorkspaceName%22), still no results are found. Yet, this workspace exists and I have access to it.

This is just a simple example, but similarly no other queries against the Workspace endpoint work such as finding by names, by any other field, using the 'contains' operator - none work.

It seems the only result I'm sometimes getting is my default workspace and even that not all the time.


What is the problem with the Workspace endpoint?
Answer:
The Workspace endpoint is a special case.

The way WSAPI works is as such where in each query (Get, Post, Put or Delete - any and all of them), the call must include
- api-key - sent as http header variable and used to authenticate and authorize the request.
- A workspace parameter. This is explained in the WSAPI Online documentation. It says:

workspace
This parameter limits the search space to a specific workspace. If not specified, then the query will search the userʼs default workspace. When used, the workspace parameter is set to the URL of the workspace to be searched as shown in the example below. ‹Workspace ObjectID› should be set to the Object ID of the workspace.
Example: workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/‹Workspace ObjectID›


The above mentioned workspace parameter is optional. If provided then the request will be executed within the mentioned workspace. If not provided, then the request will be executed within the 'default workspace' of the owner of the api-key.
Either way, any WSAPI query is executed within a given workspace.


Now, let's look at the Workspace Endpoint:
Queries against the workspace endpoint also are executed within the query's workspace (either the specified one by the parameter or the user's default). Therefore the query will be able to return results only of for the workspace that it's working under. Here are a few examples:

- WSAPI query is executing within 'workspace1', and queries information of 'workspace1' - it will work.
- WSAPI query is executing within 'workspace1', and queries information out of other workspaces - it will not work.


In your question you provided this URL:
https://rally1.rallydev.com/slm/webservice/v2.0/workspace?query=(Name = "MyWorkspaceName")&fetch=true&start=1&pagesize=20

Since no 'workspace parameter' is provided then it will work only if the api-key owner's default workspace is "MyWorkspaceName".

If it's not the default workspace, then it will work if the 'workspace parameter' is used, where 'WS_OBJECT_ID' is the ObjectID of the target workspace 'MyWorkspaceName':

https://rally1.rallydev.com/slm/webservice/v2.0/workspace?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/WS_OBJECT_ID&query=(Name = "MyWorkspaceName")&fetch=true&start=1&pagesize=20

Still, in all these examples you can only query information of a single workspace. This is the limitation of the Workspace endpoint. Therefore, you shall not query this endpoint if you need to query for workspaces. 

Solution
Instead, use the Subscription endpoint. Use this endpoint to locate your subscription and then invoke the /workspaces field to get the collection of workspaces of your subscription, then navigate the returned collection to drill-down into more information about specific workspaces:

User-added image

The workspace collection is where you will also find the ObjectID of any workspace, which you can then use to build the 'Workspace parameter' and query the Workspace endpoint for more info on that individual workspace.
Additional Information:
- You can learn more on Workspace Permissions here.