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=ChangeNumber,Description,Synopsis,Status,ModifiedTime

list=_all

Returns all properties for each item.

query={queryid}

Returns items that satisfy the query. queryid refers to a StarTeam query object defined for this component.

Back to top

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 : http://localhost:49206/serverapi/view/0/type/42?page=3&max=100&list=ChangeNumber,Description,Synopsis,Status,ModifiedTime

list=_all

Returns all properties for each item.

query={queryid}

Returns only those items that satisfy the query. queryid refers to a StarTeam query object defined for this component.

Example: http://localhost:49206/serverapi/view/0/type/42?queryID=2

Back to top

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=ChangeNumber,Description,Synopsis,Status,ModifiedTime

list=_all

Returns all properties for each item.

Back to top

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"}

Back to top

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"}

Back to top

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 }]

Back to top

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" }

Back to top

See also: