Share this page
PUT: Update an instance
To update an instance, perform a PUT on the individual entity, passing a JSON string that contains the fields to be changed.
How to update an instance
-
Use the fields metadata resource to get the fields available for the entity/resource.
Note: The data returned for an entity may contain calculated fields that cannot be POSTed or PUT.
-
Create a JSON string that contains the fields to be changed.
JSON input must be of the same format as data returned from a GET operation on the entity.
To validate the correctness of the client data and avoid accidental overrides, in the JSON string, send the client_lock_stamp field in all update requests. For details, see Lock entities.
-
PUT the data to the resource.
-
On success, the HTTP return value is 200. The returned string is the complete data of the updated entity.
Examples
Update field value for a defect
-
Request: An entity object with updated field(s).
-
Response: An entity object if the update was successful or an error object if an error occurred.
*** Request ***
PUT .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects/1019
{
"description": "This is my new description after PUTting",
"name": "This is my new name after PUTting"
}
*** Response ***
{
"type": "defect",
"id": "1019"
}
Change a work item's rank (position in the list of work items)
-
Request: An work item object with an updated rank.
-
Response: An entity object if the update was successful or an error object if an error occurred.
To set the rank of a work item, use the ordering feature to provide the ID of a work item before or after which you want to move the current work item.
| Field | Description |
|---|---|
| ordering | The ordering feature, which is an array of JSON objects. Currently, the array can have only one array value. |
| aspect | The value is always rank. Currently, the ordering feature is only available for ranking. |
| anchor | The ID of the relative work item before or after which the current work item will be ranked. |
| position | Whether the item should be ranked before or after the anchor. The position can contain the values before and after. |
Limitation: Ranking work items is supported using PUT requests. Retrieving the rank of a work item in a GET request is not supported, and null is returned.
This example demonstrates how to rank story 1019 after user story 1408, as well as modifying the name and description of the story 1019.
*** Request ***
PUT .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/stories/1019
{
"description": "This is my new description after PUTting",
"name": "This is my new name after PUTting",
"ordering": [
{
"aspect": "rank",
"anchor": {
"id": "1408"
},
"position": "after"
}
]
}
*** Response: 200 OK ***
{
"type": "story",
"id": "1019"
}
Example: PUT request for workspaces
This example demonstrates how space admins can use a PUT request in the space context to rename a specific workspace, 1234.
PUT .../api/shared_spaces/1001/workspaces/1234
{"data":[
{
"name":"NewName"
}
]
}
See also:
