The basic create, read, update, delete operations are provided according to common REST API conventions. The top-level URL for an element type represents the collection of items of that type. To render the list of all elements of that type as an array of JSON objects, use the HTTP method GET with appropriate HTTP headers or the json query parameter. To create a new element, use the HTTP method POST to the top-level URL for the appropriate type and provide JSON data for the element in the body of the request. The response body includes a full JSON representation of the new element, including the server-generated id property. You can also provide an array of JSON objects to create multiple elements in a single request. In this case, the response body contains a JSON array of the new elements in the same order that they were provided in the request. Similarly, you can update the data for multiple elements by using the HTTP PUT method with a JSON array of elements. You can delete multiple elements by using the HTTP DELETE method with a JSON array that contains either full JSON elements or only the UUIDs of the elements.
To run an operation on a single existing element, append the UUID for the element to the top-level URL for the type. For example, to access the JSON data for the sample release that is provided, use the HTTP method GET with the URL http://base_url/releases/00000000-0000-0000-0000-000000000036/. To update the data for an element, use HTTP PUT method and provide an updated JSON object in the request body. (In this case, the UUID in the request URL takes precedence over the id property in the request body.) To delete the element, use the HTTP DELETE method; no request body is required in that case.
When you use the create, read, and update operations (POST, GET, and PUT), you can include the optional format query parameter to adjust the JSON output for specific use cases. If you do not provide this parameter, or if the value of the parameter is not recognized, a default format is used. Each element type supports a different set of formats; these formats are listed with the reference information for the element type. Some formats show a large amount of detail and others show a small amount of detail, but the difference is only in the information that is shown; the values are the same.
You can use the list and detail formats with any element type. The list format provides summary information, such as you might show in a table of items. The detail format provides more detailed information. This format often includes the content of related elements. For some elements, these formats are identical. In addition, element types that have a name property also have a name format. This format includes only the id and name properties, which can be useful for displaying a list of items for selection by name. As a convenience, the name format for an element type can also be produced by appending name to the top-level URL for the type, for example, GET http://base_url/applications/name.
When you provide JSON data as input for the create or update operations, the REST API takes into account only the properties that are writable on the element. The API ignores all other data. Read-only properties, such as computed counts or creation dates, are not updated. The API ignores unrecognized properties. Properties of related elements, other than the id property used to establish a reference, are also not updated.
{
"name": "New Release",
"team": {
"id": "00000000-0000-0000-0000-000000000206",
"name": "Not the actual Team name" },
"lifecycleModel": "00000000-0000-0000-0000-000000000006",
"totalChanges": 42,
"BadProperty": "xxxx"
}
{
"name": "New Release",
"team": "00000000-0000-0000-0000-000000000206",
"lifecycleModel": "00000000-0000-0000-0000-000000000006"
}
Similarly, when you update an existing element, the API changes only the properties that you specify in the JSON input. The API does not change properties that you omit. To clear the value of a property, specify an explicit JSON null value for that property.
{
"id": "00000000-0000-0000-0000-123456789000",
"name": "New Feature",
"description": "",
"status": "In Progress",
"type": {
"id":"00000000-0000-1201-0000-000000000001",
"name":"Feature",
"icon":"feature"}
}
The following input associates the change with the sample
release, but does not update any other properties of the change.{
"id": "00000000-0000-0000-0000-123456789000",
"release": "00000000-0000-0000-0000-000000000036"
}
To reverse this operation and clear the association from
this change to the sample release, you could use the following input:{
"id": "00000000-0000-0000-0000-123456789000",
"release": null
}
{
"id": "00000000-0000-0000-0000-123456789000",
"release": "00000000-0000-0000-0000-000000000036"
}
{
"id": "00000000-0000-0000-0000-123456789000",
"release": {"id":"00000000-0000-0000-0000-000000000036"}
}
{
"id": "00000000-0000-0000-0000-123456789000",
"release": {
"id":"00000000-0000-0000-0000-000000000036",
"name":"Sample Release"}
}
{
"id": "00000000-0000-0000-0000-123456789000",
"release": {
"id":"00000000-0000-0000-0000-000000000036",
"name":"Not the actual Release name"}
}
However, in other cases, particularly if an element requires a specific relationship, you can specify input for the single-value side of the relationship. For example, an application can be associated with multiple teams. In this case, when you create an application, you can provide a JSON array of UUID strings for the "teams" property. There are no special URLs for manipulating this relationship.
Some element types support the storage and retrieval of free-form key-value pairs in addition to statically defined properties. This type of property often represents data that is linked to an integration provider. For example, a change that represents a IBM Rational® Team Concert work item might store the identifier for the work item as a property in this key-value storage.
{
"id": "00000000-0000-0000-0000-123456789000",
"name": "New Feature",
"description": "",
"status": "In Progress",
"type": {
"id":"00000000-0000-1201-0000-000000000001",
"name":"Feature",
"icon":"feature"},
"properties": {
"first":"first value",
"second":"second value",
"third":"third value"}
}
Both the key and value must be represented as JSON strings.
As with statically defined properties, if a key is omitted from input,
update operations do not change it. To clear a key-value pair, assign
a JSON null value to the key.For some element types, the top-level GET request can provide a subset of elements rather than the full list. Retrieving subsets of elements like this is commonly referred to as "pagination," because it involves loading only a single "page" of data in each request.
Two alternative forms of paging are available, using either query parameters or the HTTP Range header.
To use query parameters for pagination, specify both a rowsPerPage and a pageNumber query parameter in the HTTP GET request. To retrieve the first page, specify the code pageNumber=1. For example, to retrieve the first five applications, use the request GET http://base_url/applications/?rowsPerPage=5&pageNumber=1.
Range: items=0-4
Content-Range: 0-4/10
If
you requested the first five changes, and only three changes are available,
the header looks like this: Content-Range: 0-2/3
To sort the results of the top-level GET operation, specify the orderField and sortType parameters. The orderField parameter must contain the name of a single property to sort by. The sortType parameter must contain either the value asc to sort in ascending order, or the value desc to sort in descending order.
To sort on the properties of related elements, specify the property name with dotted-path format. For example, to sort a list of changes according to the associated release, specify the value release.name. The ordering is unspecified if any property in this path is null.
GET http://base_url/changes/?format=detail&rowsPerPage=5&
pageNumber=1&orderField=release.name&sortType=asc
Not
all properties can be used for sorting. In particular, properties
that represent summary data, such as item counts, generally cannot
be used for sorting.GET http://base_url/releases/
?filterFields=dateCreated
&filterType_dateCreated=gt
&filterClass_dateCreated=Long
&filterValue_dateCreated=1421171883574
&orderField=dateCreated
&sortType=asc
This example uses the following query
parameters:filterFields=dateCreated&filterFields=name