Last service update: 4/17/13

View known issues, FAQ at: OData Service TechNet Wiki article

Overview

The Team Foundation Server OData API is an implementation of the OData protocol built upon the existing Team Foundation Server client objet model used to connect to Team Foundation Server. The API is subject to change as we get feedback from customers.

To learn more about the OData protocol, you can browse the OData site at .

If you have questions or feedback about this service, please email TFSOData@Microsoft.com. Please note that this project is provided "as-is", with no guaranteed uptime and is not officially supported by Microsoft. But if you are having problems please let us know and we'll do our best to work with you.

See the Demo

There is a video for Channel 9 which shows how to get started using the v1 of the service. Most of the same concepts from that video still apply for this version, but a revised video has not yet been created.

Samples:

Windows 8 client (see Nisha Singh's blog entry).

Windows Phone 8 app (download here).

OData service code (see Brian Keller's blog entry). This version of the codebase can be used against on-premises deployments of Team Foundation Server 2010 and 2012, Team Foundation Service, and CodePlex.

Team Foundation Service authentication:

(Optional) In order to authenticate with Team Foundation Service, you will need to enable and configure basic auth credentials on tfs.visualstudio.com:

To authenticate against the OData service, you need to send your basic auth credentials in the following domain\username and password format:

Getting Started:

In the following section you will find meaningful information about how to consume data from Team Foundation Server taking advantage of the OData API.

Collections

The main resources available are Builds, Changesets, Changes, Builds, Build Definitions, Branches, Work Items, Attachments, Projects, Queries, Links, Area Paths, and Iteration Paths. A couple of sample queries are provided for each resource, although complete query options are provided further in this page.

Case Sensitivity: Be aware that the OData resources are case-sensitive when making queries.

Page size defaults: the default page sizes returned by the OData service are set to 20, although you can certainly use the top and skip parameters to manually control that.

Resources Path
Builds https://tfsodata.visualstudio.com/DefaultCollection/Builds

https://tfsodata.visualstudio.com/DefaultCollection/Projects('projectName')/Builds

Build Definitions https://tfsodata.visualstudio.com/DefaultCollection/Projects('projectName')/BuildDefinitions

Changesets https://tfsodata.visualstudio.com/DefaultCollection/Changesets

https://tfsodata.visualstudio.com/DefaultCollection/Projects('projectName')/Changesets

https://tfsodata.visualstudio.com/DefaultCollection/Branches('path')/Changesets

https://tfsodata.visualstudio.com/DefaultCollection/Builds(Project='prjName',Definition='BuildDef',Number='BuildNum')/Changesets
Changes https://tfsodata.visualstudio.com/DefaultCollection/Changesets(Id)/Changes
Branches https://tfsodata.visualstudio.com/DefaultCollection/Branches

https://tfsodata.visualstudio.com/DefaultCollection/Projects('prjName')/Branches
WorkItems https://tfsodata.visualstudio.com/DefaultCollection/WorkItems

https://tfsodata.visualstudio.com/DefaultCollection/Builds(Project='prjName',Definition='BuildDef',Number='BuildNum')/WorkItems

https://tfsodata.visualstudio.com/DefaultCollection/Changesets(id)/WorkItems

https://tfsodata.visualstudio.com/DefaultCollection/Projects('projectName')/WorkItems

https://tfsodata.visualstudio.com/DefaultCollection/Queries('id')/WorkItems
Attachments https://tfsodata.visualstudio.com/DefaultCollection/WorkItems(id)/Attachments
Links https://tfsodata.visualstudio.com/DefaultCollection/WorkItems(id)/Links
Projects https://tfsodata.visualstudio.com/DefaultCollection/Projects
Queries https://tfsodata.visualstudio.com/DefaultCollection/Queries
AreaPaths https://tfsodata.visualstudio.com/DefaultCollection/AreaPaths

https://tfsodata.visualstudio.com/DefaultCollection/Projects('projectName')/AreaPaths
IterationPaths https://tfsodata.visualstudio.com/DefaultCollection/IterationPaths

https://tfsodata.visualstudio.com/DefaultCollection/Projects('projectName')/IterationPaths

Individual Resources

Resource Path Related Resources Fields *
Build https://tfsodata.visualstudio.com/DefaultCollection/Builds(Project='prjName',Definition='BuildDef',Number='BuildNum') WorkItems, Changesets Project, Definition, Number, Reason, Quality, Status, RequestedBy, RequestedFor, LastChangedBy, StartTime, FinishTime, LastChangedOn, BuildFinishied, DropLocation, Errors, Warnings
Build Definition https://tfsodata.visualstudio.com/DefaultCollection/BuildDefinitions(Project='prjName',Definition='BuildDef') - Project, Definition
Changeset https://tfsodata.visualstudio.com/DefaultCollection/Changesets(id) Changes, WorkItems Id, ArtifactUri, Comment, Committer, CreationDate, Owner, Branch, WebEditorUrl
Change https://tfsodata.visualstudio.com/DefaultCollection/Changes(Changeset='id',Path='path') - Changeset, Path, Collection, ChangeType, Type
Branch https://tfsodata.visualstudio.com/DefaultCollection/Branches('path') Changesets Path, Description, DateCreated
WorkItem https://tfsodata.visualstudio.com/DefaultCollection/WorkItems(id) Attachments Id, AreaPath, IterationPath, Revision, Priority, Severity, StackRank, Project, AssignedTo, CreatedDate, CreatedBy, ChangedDate, ChangedBy, ResolvedBy, Title, State, Type, Reason, Description, ReproSteps, FoundInBuild, IntegratedInBuild, Blocked, OriginalEstimate, RemainingWork, StoryPoints, BacklogPriority, BusinessValue, Effort, Size, CompletedWork, AttachedFileCount, HyperLinkCount, RelatedLinkCount, WebEditorUrl
Attachment https://tfsodata.visualstudio.com/DefaultCollection/Attachments('WorkItemId-Index') - Id, WorkItemId, Index, AttachedTime, CreationTime, LastWriteTime, Name, Extension, Comment, Length, Uri
Project https://tfsodata.visualstudio.com/DefaultCollection/Projects('name') Changesets, Builds, BuildDefinitions, WorkItems, Queries, Branches, AreaPaths Name, Collection
Query https://tfsodata.visualstudio.com/DefaultCollection/Queries('id') WorkItems Id, Name, Description, QueryText, Path, Project, QueryType
AreaPath https://tfsodata.visualstudio.com/DefaultCollection/AreaPaths('path')

SubAreas Path, Name
User https://tfsodata.visualstudio.com/DefaultCollection/Users('user@email.com')

https://tfsodata.visualstudio.com/DefaultCollection/Users('domain:user')

- UserId, DisplayName, Id

* Id fields are displayed in bold.

Parameters Support

These are the allowed parameters for manipulating the data that comes out from the OData Service, due to the nature of the API $inlinecount and $expand are not currently supported for this service.

Name Description Values Example
filter Filter the results See filtering support section https://tfsodata.visualstudio.com/DefaultCollection/Projects?$filter=Name eq 'MyProject'
count Count the results - https://tfsodata.visualstudio.com/DefaultCollection/WorkItems/$count
top/skip Paging options Integer values https://tfsodata.visualstudio.com/DefaultCollection/WorkItems?$top=5&$skip=10
orderby Sort results Resource field https://tfsodata.visualstudio.com/DefaultCollection/Builds?$orderby=Reason asc
select Fields to return Fields for the resource type https://tfsodata.visualstudio.com/DefaultCollection/Changesets?$select=Committer,Owner
format Format of response Only 'json' supported https://tfsodata.visualstudio.com/DefaultCollection/Projects?$format=json"
callback Specify callback method if json format requested Javascript callback method https://tfsodata.visualstudio.com/DefaultCollection/Projects?$format=json&$callback=method"

Filtering Support

These are the supported fields and operations while filtering out the data that comes out from the service. All these items along with its corresponding operators can be used for filtering data.

Entity Supported Filter Operations Example
Build
  • Users can filter for a specific value (eq operator) by Project, Definition, Number, Reason, Quality, Status and RequestedFor.
  • Users can filter for a different value (ne operator) and range (eq, gt, lt operators) by RequestedBy, StartTime, FinishTime and BuildFinished.
  • Only logical And operator is supported.
https://tfsodata.visualstudio.com/DefaultCollection/Builds?$filter=Definition eq 'buildDef' and RequestedBy ne 'johndoe'
Changeset
  • Users can filter for a specific value (eq operator) by Committer and for a range of values (eq, gt and lt operators) by CreationDate.
  • Users can filter for a specific and a different value (eq and ne operators) by ArtifactUri, Comment and Owner.
  • Only logical And operator is supported.
https://tfsodata.visualstudio.com/DefaultCollection/Changesets?$filter=Committer eq 'johndoe' and ArtifactUri ne 'https://tfsserver/artifact'
Change
  • Change collections are only browsable relative to a Changeset.
https://tfsodata.visualstudio.com/DefaultCollection/Changesets(10)/Changes?$filter=Type eq 'file'
Branch
  • Users can filter for a specific value (eq operator) by Committer and for a range of values (eq, gt and lt operators) by CreationDate.
  • Users can filter for a specific and a different value (eq and ne operators) by ArtifactUri, Comment and Owner.
  • Only logical And operator is supported.
https://tfsodata.visualstudio.com/DefaultCollection/Branches?$filter=Description eq 'Release Branch'
WorkItem
  • Users can filter for a different (ne operator), a specific (eq operator), or a substring of a value (substringof operator) by AreaPath, IterationPath, Priority, Severity, StackRank, Project, AssignedTo, CreatedBy, ChangedBy, ResolvedBy, Title, State, Type, Reason, Description, ReproSteps, FoundInBuild and IntegratedInBuild.
  • Users can filter for a different (ne operator), a specific (eq operator) or a range (gt, lt, ge, le operators) of values by CreatedDate, ChangedDate and Revision.
  • Logical And and Or operators are supported.
https://tfsodata.visualstudio.com/DefaultCollection/WorkItems?$filter=Project eq 'myProject' or substringof('fixed', State) eq true
Attachment
  • Attachment collections are only browsable relative to a WorkItem.
https://tfsodata.visualstudio.com/DefaultCollection/WorkItems(5)/Attachments?$filter=Extension eq 'JPG'
Project All valid OData operations. https://tfsodata.visualstudio.com/DefaultCollection/Projects?$filter=Name eq 'myProject'
Query All valid OData operations. https://tfsodata.visualstudio.com/DefaultCollection/Queries?$filter=Name eq 'All Work Items'
AreaPath All valid OData operations. https://tfsodata.visualstudio.com/DefaultCollection/AreaPaths?$filter=Name eq 'Area 1'
BuildDefinition All valid OData operations. https://tfsodata.visualstudio.com/DefaultCollection/AreaPaths?$filter=Project eq 'MyProject'

Write Operations Support

The following entities allow write or update operations as specified by the OData specification.

Entity Supported Operations
WorkItem
  • Creating an entity through an HTTP POST operation to the main collection.
  • Updating an entity through an HTTP PUT operation to an individual resource.
Attachment
  • Creating an entity through an HTTP POST operation to the main collection.

Service Operations Support

The following custom operations are supported by the service, as specified by the OData specification.

Operation Method Request Body Description
TFSCollectionName/TriggerBuild POST Project=prjName&Definition=buildDef Triggers a new build using the Build Definition buildDef belonging to the Team Project prjName inside the TFS Project Collection named TFSCollectionName.