Visual Studio Online and Team Foundation Server 2015 REST APIs

If you’ve been following Microsoft announcements about Visual Studio Online over the last 12 months, you already know that you can easili integrate with VSO from any platform, technology, or device. Everything thanks to a new set of of JSON-based REST APIs.

Those APIs enable a lightweight way to work with Team Foundation Server from virtually any device, platform, or technology stack, including Windows, Android, iOS, Node.js, and others. You can create and query work items, get recent team room messages, queue a build, access source code, and accomplish almost any team or code management task.
All API have bees categorized and now we have following categories:

• Build
• Cloud load test
• Code policy
• Git
• Project and Teams
• Service hooks
• Shared services
• Team Room
• Test management
• Version Control
• Work Item Tracking

Detailed description of each category can be found here: Visual Studio Online REST API Reference

All those API works fine with Visual Studio Online and the TFS 2015 release candidate is the first go-live release to surface REST APIs. What’s really cool is that you can call the same APIs on both TFS and VSO, making it easy to build apps that target both environments.

Example usage

Most of APIs fallow this pattern:

   1: VERB https://{account}.VisualStudio.com/DefaultCollection/_apis[/{area}]/{resource}?api-version=1.0

So if you would like to get list of team projects you have to do such request:

   1: https://your_account_name.visualstudio.com/DefaultCollection/_apis/projects?api-version=1.0

And as a result you will get such JSON:

   1: {

   2:     "value": [

   3:         {

   4:             "id": "eb6e2456-78fc-22a1-9c81-4c9d8e8da5d1",

   5:             "name": "SimpleProject",

   6:             "url": "https: //your_account_name.visualstudio.com/DefaultCollection/_apis/projects/eb6e2456-78fc-22a1-9c81-4c9d8e8da5d1",

   7:             "description": "TeamFoundationVersionControlprojects",

   8:             "collection": {

   9:                 "id": "d82342e4-cd1a-4133-b082-1ae7d6c3ad26",

  10:                 "name": "DefaultCollection",

  11:                 "url": "https: //your_account_name.visualstudio.com/_apis/projectCollections/d82342e4-cd1a-4133-b082-1ae7d6c3ad26",

  12:                 "collectionUrl": "https: //your_account_name.visualstudio.com/DefaultCollection"

  13:             },

  14:             "defaultTeam": {

  15:                 "id": "78df9be7-3686-487b-7c5f-425c29afedfd",

  16:                 "name": "MyTeamProject",

  17:                 "url": "https: //your_account_name.visualstudio.com/DefaultCollection/_apis/projects/eb6e2456-78fc-22a1-9c81-4c9d8e8da5d1/teams/66df9be7-3586-467b-9c5f-425b29afedfd"

  18:             }

  19:         }

  20:     ],

  21:     "count": 1

  22: }

Service hooks

You can use service hooks to let your app or service get notified instantly when an event happens in Team Foundation Server. With service hooks, your app or service can avoid continuously polling to check for changes, such as completed builds, commits/check-ins, or work item changes.

How it works: A service hook subscription controls what action to perform on a target, external service when a specific type of event happens. When an event occurs and a service hook attempts to match a configured subscription to an event, a permission check is performed to ensure the user who created the subscription has permission to access to the resource associated with the event.

Everything that can be achieved using new APIs. You can find more information's here: Service hooks and here: Integrate with service hooks

TFS and Visual Studio Online .NET client object model

There is couple of NuGet packages which allows user to interact with Visual Studio Online and TFS in the object oriented way:

• Microsoft.TeamFoundationServer.ExtendedClient - package contains the traditional TFS/VSO client object model that uses the SOAP API. Because not every API is available in TFS 2015 or VSO currently as a REST API, there are going to be cases where you must use this package. Similarly, there are new features that have been built with only REST APIs for which you will need the Client package.
• Microsoft.TeamFoundationServer.Client - .NET wrappers for REST APIs for build, team rooms, version control, test case management, and work item tracking.
• Microsoft.VisualStudio.Services.Client – provides access to shared platform services such as account, profile, identity, security, and more via public REST APIs.
• Microsoft.VisualStudio.Services.InteractiveClient – this one allows to integrate with Visual Studio Online from desktop-based Windows applications that require interactive sign-in by a user.

The licence allows you to bundle these libraries with your application so there is no problem with redistributing them.

Example of calling both REST and SOAP-based APIs:

   1: //getting projects collection using standard SOAP convention

   2: using (TfsTeamProjectCollection tpc = new TfsTeamProjectCollection(new Uri(collectionUri)))

   3: {

   4:     //can retrieve SOAP service from TfsTeamProjectCollection instance

   5:     VersionControlServer vcServer = tpc.GetService<VersionControlServer>();

   6:     ItemSet itemSet = vcServer.GetItems("$/", RecursionType.OneLevel);

   7:     foreach (Item item in itemSet.Items)

   8:     {

   9:         Console.WriteLine(item.ServerItem);

  10:     }

  11:  

  12:     //can retrieve REST client from same TfsTeamProjectCollection instance

  13:     TfvcHttpClient tfvcClient = tpc.GetClient<TfvcHttpClient>();

  14:     List<TfvcItem> tfvcItems = tfvcClient.GetItemsAsync("$/", VersionControlRecursionType.OneLevel).Result;

  15:     foreach (TfvcItem item in tfvcItems)

  16:     {

  17:         Console.WriteLine(item.Path);

  18:     }

  19: }