Overview

The CodePlex OData API is an implementation of the OData protocol built upon the existing Team Foundation Server 2010 API used to connect to CodePlex. 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 service 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 service.

Download the Demo

Download the demo which includes the source code and the full documentation. The service can be easily hosted in Windows Azure to front-end your own Team Foundation Server instance.

Getting Started

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

While reviewing the available operations you will notice that you need to include a valid TFS Project Collection name as part of the URL. For example, if you want to target the TFS Project Collection named TFS18 you need to use browse https://codeplexodata.cloudapp.net/TFS18.

To find out the right TFS Project Collection for a specific CodePlex project follow these steps:

Collections

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

Resources Path
Builds https://codeplexodata.cloudapp.net/TFSCollectionName/Builds

https://codeplexodata.cloudapp.net/TFSCollectionName/Projects('projectName')/Builds

Build Definitions https://codeplexodata.cloudapp.net/TFSCollectionName/Projects('projectName')/BuildDefinitions

Changesets https://codeplexodata.cloudapp.net/TFSCollectionName/Changesets

https://codeplexodata.cloudapp.net/TFSCollectionName/Projects('projectName')/Changesets

https://codeplexodata.cloudapp.net/TFSCollectionName/Branches('path')/Changesets

https://codeplexodata.cloudapp.net/TFSCollectionName/Builds(Project='prjName',Definition='BuildDef',Number='BuildNum')/Changesets
Changes https://codeplexodata.cloudapp.net/TFSCollectionName/Changesets(Id)/Changes
Branches https://codeplexodata.cloudapp.net/TFSCollectionName/Branches

https://codeplexodata.cloudapp.net/TFSCollectionName/Projects('prjName')/Branches
WorkItems https://codeplexodata.cloudapp.net/TFSCollectionName/WorkItems

https://codeplexodata.cloudapp.net/TFSCollectionName/Builds(Project='prjName',Definition='BuildDef',Number='BuildNum')/WorkItems

https://codeplexodata.cloudapp.net/TFSCollectionName/Changesets(id)/WorkItems

https://codeplexodata.cloudapp.net/TFSCollectionName/Projects('projectName')/WorkItems

https://codeplexodata.cloudapp.net/TFSCollectionName/Queries('id')/WorkItems
Attachments https://codeplexodata.cloudapp.net/TFSCollectionName/WorkItems(id)/Attachments
Projects https://codeplexodata.cloudapp.net/TFSCollectionName/Projects
Queries https://codeplexodata.cloudapp.net/TFSCollectionName/Queries
AreaPaths https://codeplexodata.cloudapp.net/TFSCollectionName/AreaPaths

https://codeplexodata.cloudapp.net/TFSCollectionName/Projects('projectName')/AreaPaths

Individual Resources

Resource Path Related Resources Fields *
Build https://codeplexodata.cloudapp.net/TFSCollectionName/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://codeplexodata.cloudapp.net/TFSCollectionName/BuildDefinitions(Project='prjName',Definition='BuildDef') - Project, Definition
Changeset https://codeplexodata.cloudapp.net/TFSCollectionName/Changesets(id) Changes, WorkItems Id, ArtifactUri, Comment, Committer, CreationDate, Owner, Branch, WebEditorUrl
Change https://codeplexodata.cloudapp.net/TFSCollectionName/Changes(Changeset='id',Path='path') - Changeset, Path, Collection, ChangeType, Type
Branch https://codeplexodata.cloudapp.net/TFSCollectionName/Branches('path') Changesets Path, Description, DateCreated
WorkItem https://codeplexodata.cloudapp.net/TFSCollectionName/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, WebEditorUrl
Attachment https://codeplexodata.cloudapp.net/TFSCollectionName/Attachments('WorkItemId-Index') - Id, WorkItemId, Index, AttachedTime, CreationTime, LastWriteTime, Name, Extension, Comment, Length, Uri
Project https://codeplexodata.cloudapp.net/TFSCollectionName/Projects('name') Changesets, Builds, BuildDefinitions, WorkItems, Queries, Branches, AreaPaths Name, Collection
Query https://codeplexodata.cloudapp.net/TFSCollectionName/Queries('id') WorkItems Id, Name, Description, QueryText, Path, Project, QueryType
AreaPath https://codeplexodata.cloudapp.net/TFSCollectionName/AreaPaths('path')

SubAreas Path, Name

* 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://codeplexodata.cloudapp.net/TFSCollectionName/Projects?$filter=Name eq 'MyProject'
count Count the results - https://codeplexodata.cloudapp.net/TFSCollectionName/WorkItems/$count
top/skip Paging options Integer values https://codeplexodata.cloudapp.net/TFSCollectionName/WorkItems?$top=5&$skip=10
orderby Sort results Resource field https://codeplexodata.cloudapp.net/TFSCollectionName/Builds?$orderby=Reason asc
select Fields to return Fields for the resource type https://codeplexodata.cloudapp.net/TFSCollectionName/Changesets?$select=Committer,Owner

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://codeplexodata.cloudapp.net/TFSCollectionName/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://codeplexodata.cloudapp.net/TFSCollectionName/Changesets?$filter=Committer eq 'johndoe' and ArtifactUri ne 'https://tfsserver/artifact'
Change
  • Change collections are only browsable relative to a Changeset.
https://codeplexodata.cloudapp.net/TFSCollectionName/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://codeplexodata.cloudapp.net/TFSCollectionName/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://codeplexodata.cloudapp.net/TFSCollectionName/WorkItems?$filter=Project eq 'myProject' or substringof('fixed', State) eq true
Attachment
  • Attachment collections are only browsable relative to a WorkItem.
https://codeplexodata.cloudapp.net/TFSCollectionName/WorkItems(5)/Attachments?$filter=Extension eq 'JPG'
Project All valid OData operations. https://codeplexodata.cloudapp.net/TFSCollectionName/Projects?$filter=Name eq 'myProject'
Query All valid OData operations. https://codeplexodata.cloudapp.net/TFSCollectionName/Queries?$filter=Name eq 'All Work Items'
AreaPath All valid OData operations. https://codeplexodata.cloudapp.net/TFSCollectionName/AreaPaths?$filter=Name eq 'Area 1'
BuildDefinition All valid OData operations. https://codeplexodata.cloudapp.net/TFSCollectionName/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.