WS API request examples using curl and browser REST client
Article ID: 57596
Updated On:
Products
Issue/Introduction
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 the documentation.
The article considers both APIKey and username/password authentication scenarios.
Resolution
OTE: Examples explicitly set request's workspace using a 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:<API Key - include the underscore at the beginning of the key too>" -H "Content-Type: application/json" https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement?workspace=workspace/<Workspace OID>
2. GET request with curl using basic authentication (username:password)
curl -u [email protected]:secret' -H "Content-Type: application/json" https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement?workspace=workspace/<Workspace OID>
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.
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:
b) Click on 'value' box. 'Construct' button will appear:
c) Click on 'Construct' button:
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:
e) Enter username/password in Basic 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"
5. POST request with curl using ApiKey
curl --header "zsessionid:<API Key - include the underscore before the key>" -H "Content-Type: application/json" -d"{\"Tag\":{\"Workspace\":{\"_ref\":\"/workspace/<Workspace OID>\"},\"Name\":\"MyTag\"}}" https://rally1.rallydev.com/slm/webservice/v2.0/tag/create?workspace=workspace/<Workspace OID>
6. POST request with browser REST client using ApiKey
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:
Payload:
https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement/<Story OID>
Payload:
?
{
"HierarchicalRequirement":{
"c_CustomDropDown": "one"
}
Returned json:
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 intend 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/<Workspace OID>?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/<Workspace OID>
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, <WS1 OID> 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/<Testcase OID>","Workspace":"/workspace/<Workspace OID>","Verdict":"Pass","Date":"2015-06-25","Tester":"/user/<User OID>"}}
Here is an equivalent request made in curl:
curl --header "zsessionid:<API Key - include the underscore at the beginning of the key too>" -H "Content-Type: application/json" -d"{\"TestCaseResult\":{\"Build\":\"6.0\",\"TestCase\":\"/testcase/23680245388\",\"Workspace\":\"/workspace/<Workspace OID>\",\"Verdict\":\"Pass\",\"Date\":\"2015-06-25\",\"Tester\":\"/user/20698116479\"}}" https://rally1.rallydev.com/slm/webservice/v2.0/testcaseresult/create
Additional Information
Keywords: wsapi rally agile central
Feedback
