Share this page
Items
This topic describes the usage of the StarTeam REST API for items.
GET - typeid
The following section illustrates the usage of the GET method with typeid for a project or view:
Usage: GET: /project/{id}/view/{viewid}/type/{typeid} or GET: /view/{viewid}/type/{typeid}
Description: Gets a list of items of type {typeid} in view {viewid} and project{id}. The project is optional.
Gets a list of items of type {typeid} in view {viewid}.
By default, for each item it returns the following:
- ItemID
- Primary descriptor
- Secondary descriptor (if available).
Sample URL: http://localhost:49206/serverapi/project/0/view/0/type/42 (using cookie)
Response example
{"paging":{"page":0,"pages":40,"totalitems":1000},
"project.ID":0,"project.Name":"test",
"properties":
[{"ChangeNumber":1,"ItemID":11,"Synopsis":"ew"},
{"ChangeNumber":2,"ItemID":25,"Synopsis":"featurework"},
{"ChangeNumber":3,"ItemID":26,"Synopsis":"feature "},
{"ChangeNumber":4,"ItemID":27,"Synopsis":"does not work"},
{"ChangeNumber":5,"ItemID":28,"Synopsis":" work"},
{"ChangeNumber":6,"ItemID":29,"Synopsis":"feature does not work"},
{"ChangeNumber":7,"ItemID":30,"Synopsis":"feature does not work"},
{"ChangeNumber":8,"ItemID":31,"Synopsis":"feature does not work"}]
,"type.ID":42,
"type.Name":"Change",
"view.ID":0,
"view.Name":"test"}
URL parameters
| Parameter name | Description |
|---|---|
|
page={pageno} |
The page number to be returned, default is the first page, 25 items per page. |
|
max={integer] |
The maximum number of items per page, default is 25 items per page. |
|
list={propertyname}, {propertyname}…. |
The properties to be returned for each item. Example: |
|
list=_all |
Returns all properties for each item. |
|
query={queryid} |
Returns items that satisfy the query. |
GET - typeid with label
The following section illustrates the usage of the GET method with typeid of a specific label:
Usage: GET: /view/{viewid}/label/{labelid}/type/{typeid}
Description: Gets a list of items of type {typeid} using configuration {label} for view {viewid}.
Note: This API cannot be used with revision labels. It gets a list of items of type {typeid} in view {viewid} included in label {labelid}. By default, for each item it returns the following properties:
- ItemID
- Primary descriptor
- Secondary descriptor (if available)
Sample URL: http://localhost:49206/serverapi/view/0/label0/type/42
Response example
{"paging":{"page":0,"pages":40,"totalitems":1000},
"project.ID":0,"project.Name":"test",
"properties":
[{"ChangeNumber":1,"ItemID":11,"Synopsis":"ew"},
{"ChangeNumber":2,"ItemID":25,"Synopsis":"featurework"},
{"ChangeNumber":3,"ItemID":26,"Synopsis":"feature "},
{"ChangeNumber":4,"ItemID":27,"Synopsis":"does not work"},
{"ChangeNumber":5,"ItemID":28,"Synopsis":" work"},
{"ChangeNumber":6,"ItemID":29,"Synopsis":"feature does not work"},
{"ChangeNumber":7,"ItemID":30,"Synopsis":"feature does not work"},
{"ChangeNumber":8,"ItemID":31,"Synopsis":"feature does not work"}]
,"type.ID":42,
"type.Name":"Change",
"view.ID":0,
"view.Name":"test"}
URL parameters
| Parameter name | Description |
|---|---|
|
page={pageno} |
The page number to be returned, default is the first page. |
|
max={integer] |
The maximum number of items per page, default is 25 items per page. |
|
list={propertyname}, {propertyname}…. |
The properties to be returned for each item. Example : |
|
list=_all |
Returns all properties for each item. |
|
query={queryid} |
Returns only those items that satisfy the query. Example: |
GET - typeid properties
The following section illustrates the usage of the GET method to get the properties of typeid for a view and project:
Usage: GET: /project/{id}/view/{viewid}/item{id} or GET: /view/{viewid}/item{id} or GET: /item/{itemid}
Description: Gets the properties of {itemid} in view {viewid} and in project {id}). Project and view are optional, and the response will indicate them.
By default, it returns the following properties for each item:
- ItemID
- Primary descriptor
- Secondary descriptor (if available)
Sample URLs:
http://localhost:49206/serverapi/project/0/view/0/item/25 (using cookie)
http://localhost:49206/serverapi/view/0/item/25
http://localhost:49206/serverapi/item/25
Response example
{
"ItemID": 25,
"project.ID": 0,
"project.Name": "test",
"properties": {
"ChangeNumber": 2,
"Description": "QA found an issue",
"ItemID": 25,
"ModifiedTime": {
"raw": 43693.9001918056,
"text": "2019-08-16T21:36:16Z"
},
"Status": 1,
"Synopsis": "feature does not work"
},
"type.ID": 42,
"type.Name": "Change",
"view.ID": 0,
"view.Name": "test"
}
URL parameters
| Parameter name | Description |
|---|---|
|
list={propertyname}, {propertyname}…. |
The properties to be returned for each item. Example: |
|
list=_all |
Returns all properties for each item. |
GET typeid history
The following section illustrates the usage of the GET method to get the history of typeid:
Usage: GET: /item/{itemid}/history
Description: Gets history information of {itemid}. Project and view are optional and the response will indicate them.
Sample URL: http://localhost:49206/serverapi/item/83/history
Response example
{"ItemID":83,"Revisions":
[{"Comment":"","DotNotation":"1.2","ObjectID":59,"PathRevision":3,"Revision":2,"Time":{"raw":43697.012399409701,"text":"2019-08-20T00:17:51Z"},"UserID":0,"ViewID":0},
{"Comment":"","DotNotation":"1.1","ObjectID":59,"PathRevision":2,"Revision":1,"Time":{"raw":43693.908671655103,"text":"2019-08-16T21:48:29Z"},"UserID":0,"ViewID":0},
{"Comment":"","DotNotation":"1.0","ObjectID":59,"PathRevision":1,"Revision":0,"Time":{"raw":43693.900247650497,"text":"2019-08-16T21:36:21Z"},"UserID":0,"ViewID":0}],
"project.ID":0,"project.Name":"test","type.ID":42,"type.Name":"Change","view.ID":0,"view.Name":"test"}
POST - add typeid item
The following section illustrates the usage of the POST method to add an item of typeid to view:
Usage: POST: /view/{viewid}/type/{typeid}
Description: Adds an item of type {typeid} to view {viewid}. The body should contain a list of properties for the new item. To add multiple items at once, create an array of properties.
Sample URL: http://localhost:49206/serverapi/view/0/type/42
Body example 1 — Add one item
"properties": {
"Description": "QA found an issue",
"Synopsis": "feature does not work",
"Status": 1
Body example 2 — Add multiple items
"properties":[
{ "Description": "QA found an issue",
"Synopsis": "feature1 does not work",
"Status": 1 }
{ "Description": "QA found another issue",
"Synopsis": "feature 2 does not work",
"Status": 1 }]
Response example 1
{"ItemID":1029,
"project.ID":0,
"project.Name":"test",
"properties":
{"AddressedBy":-1,"AddressedIn":-1,"AddressedInView":-1,"AttachmentCount":0,"AttachmentIDs":[],"AttachmentNames":[],"BranchOnChange":0,"BranchState":2,"Category":"","ChangeNumber":1001,"ClosedOn":{"raw":0,"text":""},"Comment":"","CommentID":-1,"Component":"","ConfigurationTime":{"raw":0,"text":""},"CreatedTime":{"raw":43697.929851215296,"text":"2019-08-20T22:18:59Z"},"CreatedUserID":0,"DeletedTime":{"raw":0,"text":""},"DeletedUserID":-1,"Description":"QA found an issue","DotNotation":"1.0","EndModifiedTime":{"raw":0,"text":""},"EnteredBy":0,"EnteredOn":{"raw":43697.929851215296,"text":"2019-08-20T22:18:59Z"},"ExclusiveLocker":-1,"ExternalID":"","ExternalReference":"","ExternalURL":"","Fix":"","FlagUserList":[],"GlobalID":1029,"ID":1000,"ItemDeletedTime":{"raw":0,"text":""},"ItemDeletedUserID":-1,"ItemID":1029,"LastBuildTested":-1,"ModifiedTime":{"raw":43697.929851215296,"text":"2019-08-20T22:18:59Z"},"ModifiedUserID":0,"NonExclusiveLockers":"","NotificationIDs":[],"ParentObjectID":-1,"ParentRevision":-1,"PathRevision":0,"Platform":0,"Priority":0,"ReadOnly":0,"ReadStatusUserList":[],"ResolvedOn":{"raw":0,"text":""},"Responsibility":-1,"RevisionFlags":0,"RevisionNumber":0,"RootObjectID":1000,"Severity":1,"ShareState":1,"ShortComment":"","Status":1,"StreamState":0,"Synopsis":"feature does not work","TestCommand":"","Type":0,"Usr_StatusDup":0,"VerifiedOn":{"raw":0,"text":""},"ViewID":1,"WorkAround":""},
"type.ID":42,
"type.Name":"Change",
"view.ID":1,
"view.Name":"dev"}
PUT - update items by typeid
The following section illustrates the usage of the PUT method to update items of typeid in view:
Usage: PUT: /view/{viewid}/type/{typeid}
Description: Updates multiple items of type {typeid} in view {viewid}. The body should contain an array of properties for the new items, including the ItemID. Items should all be of type {typeid}.
The ModifiedTime property is used to validate if the item is current.
Sample URL:
http://localhost:49206/serverapi/view/0/type/42
Body example
The following example changes the Status property for multiple items, items 85 and 84.
"properties":[
{ "ItemID": 85, "Status": 4 }
{ "ItemID": 84, "Status": 4 }]
PUT - update items by ItemID
The following section illustrates the usage of the PUT method to update items by ItemID:
Usage: PUT: /item/{id}
Description: Updates an item by ItemID. The body should contain the properties to be updated.
Sample URL: http://localhost:49206/serverapi/item/85
Body example
"properties":
{ "Status": 4, “Fix”: "how I fixed it" }
See also:
