WS API request examples using curl and browser REST client

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

Issue

The examples in this article can be used to make quick get and post requests.
The examples can also be used to confirm if valid credentials are used in a custom code. For example, if a java or c# code returns 401, a quick WS API request using curl or a browser REST client may confirm if the issue is related to credentials or the code.
The article assumes that a user generated an API Key following steps outlined in CA Agile Central Application Manager documentation.
The article considers both APIKey and username/password authentication scenarios.

Resolution

NOTE: examples explicitly set request's workspace using workspace query parameter. Use the same workspace that your code uses.


1. GET request with curl using ApiKey

Use ApiKey to set zsessionid as shown below:

curl --header "zsessionid:_abc123" -H "Content-Type: application/json" https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement?workspace=workspace/12352608129

2. GET request with curl using basic authentication (username:password)

curl -u user@company.com:secret' -H "Content-Type: application/json" https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement?workspace=workspace/12352608129

3. GET request with browser REST client using ApiKey

A disadvantage of using the browser is a possibility of cached credentials. Make sure to run this in incognito mode.

User-added image

4. GET request with browser REST client using basic authentication (username:password)


Depending on your choice of a REST client this option may not be obvious. The screenshots below show this hidden feature in Chrome's Advanced REST Client.
a) Add Authorization header:

User-added image

b) Click on 'value' box. 'Construct' button will appear:

User-added image
c) Click on 'Construct' button:
User-added image

d) (Optional) To make sure that this UI is working as it should, enter wrong credentials. "Authentication Required" popup box will appear. If it's closed without supplying credentials, 401 should be returned:

User-added image

e) Enter username/password in Baisic tab shown in step (c) if you skipped the optional (d) or edit username/password if you tested with a wrong password in step (d). Click "Send"

User-added image
User-added image

5. POST request with curl using ApiKey

curl --header "zsessionid:_abc123" -H "Content-Type: application/json" -d"{\"Tag\":{\"Workspace\":{\"_ref\":\"/workspace/29047390143\"},\"Name\":\"MyTag\"}}" https://rally1.rallydev.com/slm/webservice/v2.0/tag/create?workspace=workspace/29047390143

6. POST request with browser REST client using ApiKey

User-added image
User-added image

Using basic authentication for POST requests is more complicated (and can be brittle) since it requires a security token. On Sandbox however it is the only option since Sandbox does not support ApiKey authentication.
See? How to create and update an artifact in sandbox via WS API for details on how to generate and use the security token on rally1.rallydev.com or on sandbox.rallydev.com.

7. POST request with browser REST client using ApiKey to update a custom field

One more example of a POST request. In this example a custom field?on a user story is updated. Before making the request we make sure that a custom field's value is set to one of the allowed valued shown in WS API document:

User-added image

Payload:

https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement/35964898408

Payload:
?
{
"HierarchicalRequirement":{
"c_CustomDropDown": "one"
}

User-added image

Returned json:

User-added image

If a custom field of a dropdown type is being updated with a value that is not on a list of AllowedValues, as in a payload example below:
{
"HierarchicalRequirement":{
"c_CustomDropDown": "wrongvalue"
}
}

this error is returned:

{"OperationResult": {"_rallyAPIMajor": "2", "_rallyAPIMinor": "0", "Errors": ["Validation error: HierarchicalRequirement.CustomDropDown wrongvalue is an invalid value"], "Warnings": []}}

If a custom field of? is referenced by a wrong name, as in a payload example below:

{
"HierarchicalRequirement":{
"c_WrongCustomDropDown": "one"
}
}

this warning is returned, and the update of the intended field does not take place:

{"OperationResult": {"_rallyAPIMajor": "2", "_rallyAPIMinor": "0", "Errors": [], "Warnings": ["Ignored JSON element HierarchicalRequirement.c_WrongCustomDropDown during processing of this request."]

Important: The warning?"Ignored JSON element HierarchicalRequirement.c_CustomDropDown may be returned even if the custom field is referenced with the correct name. This happens when your requests implicitly scoped to a workspace that is different from the one where you intent to? post a request. For example, let's say a user has two CA Agile Central workspaces, W1 and W2, while c_CustomDropDown exists in W1 only. The same endpoint and payload used in a browser REST client will succeed if the user is logged in to W1 workspace in another tab of the same browser window, and will fail if the user is logged in to W2 workspace in another tab of the same browser window.

The solution in that case to scope explicitly. Here is an example of the endpoint scoped explicitly:
https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement/35964898408?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/29047390143

Using an endpoint scoped explicitly to the intended workspace, will allow the request to succeed even if a user is currently logged in to the "wrong" workspace in another tab of the same browser window. In this example, 29047390143 is ObjectID of W1 workspace.

8. POST request with browser REST client and curl using ApiKey to create TestCaseResult


URL:

https://rally1.rallydev.com/slm/webservice/v2.0/testcaseresult/create

Payload:

{"TestCaseResult":{"Build":"10.0","TestCase":"/testcase/12476262570","Workspace":"/workspace/12352608129","Verdict":"Pass","Date":"2015-06-25","Tester":"/user/32426897620"}}

User-added image

Here is an equivalent request made in curl:

curl --header "zsessionid:_ab123" -H "Content-Type: application/json" -d"{\"TestCaseResult\":{\"Build\":\"6.0\",\"TestCase\":\"/testcase/23680245388\",\"Workspace\":\"/workspace/12352608129\",\"Verdict\":\"Pass\",\"Date\":\"2015-06-25\",\"Tester\":\"/user/20698116479\"}}" https://rally1.rallydev.com/slm/webservice/v2.0/testcaseresult/create

Related articles:
Oauth Client and ApiKey FAQ
How to use API Key with cURL
How to use API Key with AppSDK2