Visual Studio Online Rest API introduction and sample on GitHub.

Visual Studio Online opens its chest with APIs, with this creating an open platform for managing team work and collaboration. An open Application Lifecycle Management platform, for everybody to use, consume and integrate.

Not only Rest APIs for project artifacts are available, also a notification mechanism via Service Hooks is.

In this post an overview of the Rest APIs supported by examples and a solution, in the next one an introduction to Service Hooks.

You can get the source over here on GitHub VSOTeams-Universal-App

(this small project I created when we moved to Azure AD to get all our VSO users in an Excel file, with license information and mail to add them in bulk to Azure AD. Not complete and a lot of room for improvement. Below a detailed description of the scenario and video)

Introduction Visual Studio Online Rest API’s

Visual Studio Online Rest APIs lets you build functionality on top of Visual Studio Online with simple HTTP methods in JSON format. This makes the Visual Studio Online Rest APIs (VSO APIs) an ideal extensibility capability for Mobile and Web Apps.

The VSO APIs opens up the Visual Studio Online SaaS platform. The Visual Studio Online platform provides functionality for teams like; Agile planning, TFS / GIT version control, test management, bug tracking, team collaboration, build management and more. All these capabilities are accessible via the VSO APIs to leverage applications or integrate with third-party ALM vendor tools.

Getting started with Visual Studio Online Rest APIs.

The only prerequisite needed to start building on top of the Visual Studio Online platform is a Visual Studio Online account. A free Visual Studio Online account can easily be created via www.VisualStudio.com with a Microsoft Account.

image

Visual Studio Online API organization

The VSO APIs can be grouped in three levels, with different URL formats.

Personal Level.

To get information about your profile as known in VSO and the VSO accounts your account has. The URL format of these calls start with:

https://app.vssps.visualstudio.com/_apis/.../...

For example to get your profile from VSO the request will be:

https://app.vssps.visualstudio.com/_apis/profile/profiles/me which gives a JSON response with the current signed in User.

{

"displayName": "Clemens Reijnen",

"publicAlias": "4b128a7c-0e4d-4a75-b36e-1f2151220asdad",

"emailAddress": "clemens.reijnen@sogeti.nl",

"coreRevision": 79,

"timeStamp": "2014-05-05T10:50:49.77+00:00",

"id": "4b128a7c-0e4d-4a75-b36e-1f2151220asdad",

"revision": 1613

}

For accounts of the current users the URL will look like this:

https://app.vssps.visualstudio.com/_apis/Accounts

Account level.

VSO APIs on the account level provide information about users and licenses in the account.

https:// {account}.vssps.visualstudio.com/_apis/…/…

To get all users in a Visual Studio Online account with corresponding licenses you create a responds like:

https://sogeti.vssps.visualstudio.com/_apis/Licensing/Entitlement

Project collection level.

The project level APIs are most interesting for leveraging VSO functionality in Apps. These APIs provide information and actions on:

- Work Item tracking,

- Builds,

- GIT,

- Version Control,

- Test Management,

- Team rooms.

Project collection level APIs have the format of:
https://{account}.VisualStudio.com/DefaultCollection/_apis[/{area}]/{resource}

For example a request to get all projects in a project collection can be captured with request like:

https://sogeti.visualstudio.com/DefaultCollection/_apis/projects

Which give a JSON array response with all projects in the DefaultCollection.

"value": [

{

"id": "810f92d5-cbb2-41e8-9390-08f1fc5c123",

"name": "WIN8 Store App Development",

"url": "https://sogeti.visualstudio.com/DefaultCollection/_apis/projects/810f92d5-cbb2-41e8-9390-08f1fc5c123",

"collection":

{

"id": "d62d8b1e-06b9-4132-bb09-c3b45123",

"name": "DefaultCollection",

"url": "https://sogeti.visualstudio.com/_apis/projectCollections/d62d8b1e-06b9-4132-bb09-c3b453",

"collectionUrl": "https://sogeti.visualstudio.com/DefaultCollection"

},

"defaultTeam":

{

"id": "6c831d9a-f061-4bee-bd85-13c4f53d8",

"name": "WIN8 Store App Development Team",

"url": "https://sogeti.visualstudio.com/DefaultCollection/_apis/projects/810f92d5-cbb2-41e8-9390-0234fc5cb90d/teams/6c831d9a-f061-4bee-bd85-4f525f3d8"

}

},

]

VSO Rest APIs URL property.

The URL property found in most JSON responses gives an easy access to the underlying properties of the requested project artifact.

For example in the JSON response of the above Projects request you will recognize the URL properties with the already populated Request URL for more details.

For example to get from the projects array JSON responds to detailed project team information you can use the URL references.

clip_image002

Note: I’m using Chrome with a JSON formatter app installed, for getting the nice readable JSON responds.

HTTP Verbs.

Beside the GET HTTP verb are the others, POST, PATCH and DELETE .

With POST you can create resource as Work Items and Team Rooms.

First get a list with Rooms, to get the RoomId.

https://sogeti.visualstudio.com/DefaultCollection/_apis/chat/rooms

And then POST a message to the room with the RoomId

https://Sogeti.VisualStudio.com/DefaultCollection/_apis/chat/rooms/{roomId}/messages

and the message you want to post:

{

"content": "New messages"

}

PATCH can be used to update a resource and DELETE for deleting resources.

Authentication.

While getting the responses in the above example doesn’t require any specific authentication mechanisms, you’re already logged on in Visual Studio Online via the browser. But, when you want to call the VSO APIs from outside the browser you need enable your secondary credentials to make us of Basic Authentication.

Enabling your secondary credentials can easily be done from within Visual Studio Online via your “My profile”.

clip_image003

Once enabled Apps can make use of these credentials to request information from the VSO APIs.

One attention point on the usage of the Basic Authentication credentials, beside that it isn’t the most secure way, when using an automated system to request information you can run in to a block from Visual Studio Online.

clip_image005

OAuth

Visual Studio Online also provides a more easier, end user friendly and more secure way of consuming its API’s via OAuth. See http://www.visualstudio.com/en-us/integrate/get-started/get-started-auth-oauth2-vsi 

Visaul Studio Online authorization page with your company and app information

Use Visual Studio Online Rest API’s in a Universal Windows App.

The Visual Studio Online Rest APIs are ideal for mobile apps to extend its capabilities. Scenario’s where Team members want to take a quick look at the team activity of the past day they want to see the latest build results and details, change set. The scenarios for mobile are unlimited.

 

For sources used in this example application see: GitHub You can get the source over here on GitHub https://github.com/Clemensreijnen/VSOTeams-Universal-App 

The example App scenario.

The example solution is a Universal Windows App which displays the projects in a Visual Studio Online account with the Teams in these projects. For a Team the solution shows its team members and team room messages. For sure the solution also has the capability to post messages to the team room.

clip_image007

For the team members the solution shows their person details with Visual Studio license, and teams they are member of.

A video says more than thousand mocks… YouTube: VSO Teams

VSO Teams

The Rest APIs necessary are:

- Get logged in user identity
https://app.vssps.visualstudio.com/_apis/Profile/profiles/me this results in the JSON respond with the UserID, which is needed for the next call.

- Get logged in user accounts
https://app.vssps.visualstudio.com/_apis/Accounts?memberId=UserId
when multiple accounts are return a selection needs to be made in the settings, this setting is used in the call to get all projects.

- Get all projects in account
https:/{account}.visualstudio.com/DefaultCollection/_apis/projects/

- Get teams per project
https:// {account}.visualstudio.com/DefaultCollection/_apis/projects/{ProjectID}/teams
probably multiple projects are returned, so a iteration to the projects collection is needed to get all the Teams.

- Get activities in team room
https://{account}.VisualStudio.com/DefaultCollection/_apis/chat/rooms/{roomId}/messages
Per Team Room the messages are captured. All the other calls are more stable, they don’t change that often, this one will be called multiple times to get new messages. A filter can be added to this call in the form of timespan.

- Post activity in team room
https://{account}.VisualStudio.com/DefaultCollection/_apis/chat/rooms/{roomId}/messages with the message.

For the users screen a list of all account users with licenses is needed and user details.

- Get All VSO Users
https:// {account}.vssps.visualstudio.com/_apis/Licensing/Entitlement

- Get user details, this one is a bit complex because we only can get the details from team members, so we need to iterate all teams to get a collection of team members.

https://{account}.visualstudio.com/DefaultCollection/_apis/projects/{ProjectID}/teams/{TeamID}/members

- And finally we get all account pictures.
https://sogeti.visualstudio.com/DefaultCollection/_api/_common/identityImage?id={UserID}

Very straight forward. But before we can move forward we need to create the project and authenticate the user in the App for Visual Studio Online (with secondary credentials).

The Universal App.

The universal app needs a bit different approach as when you’re building separate Apps for the different Windows platforms. Lucky it gets easier.

clip_image009

Authentication.

Basic Authentication can be implemented with the “Windows.Web.Http” API as shown in the below.

clip_image011

Basic Authentication is very straight forward, the HTTPClient from Windows.Web.Http can be used for asynchronous operations for various types of content to a HTTP server.

Call VSO Rest API for projects

With the authentication in place a call can be made to the VSO Rest API for projects. The asynchronous method “GetAsync” is used. After ensuring that there is a success (200) callback, the response is read in a string and de-serialized to a projects collection.

clip_image013

The JsonConvert method is used from Newtonsoft JSON. The Project collection is an Observable Collection with Observable objects of the type project.

clip_image015

The property name value is extracted from the returned JSON string. Where collections in VSO Rest API responses come with a JSON array {"value": [ … ]}

Pretty easy to use is http://json2csharp.com/ to convert the JSON to C3 objects, although we finally we still have to make the objects observable.

With the collection of Projects in place we now can bind them to the screens in XAML. But, first the JSON is saved in local storage. Because the projects don’t change that often, not every minute a project is added to VSO accounts, we can make starting up the project faster and we have offline capabilities.

Now all project are loaded in the Windows 8.1 Store App

image

And the Windows 8 Phone App (still some XAML work to do)

clip_image019

We can repeat this for all the GET operation needed to get the proper information, except for the profile images. For the profile images not a string responds is captured but a buffer is written in a stream to get the image file.

clip_image021

Also this method saves the images local, you defiantly don’t want to do this every time you load the App.

See for more detailed implementation the Sources of this Universal App on Codeplex.

Wrapping Up.

Using the Visual Studio Online Rest APIs is very straight forward and easy. For the mobile apps scenario, having the data offline is defiantly a must, especially when you are loading lots of content from VSO like this example. Updating content in the Apps with Service Hooks is a very interesting scenario, which will be explained in the next post.

But not only Mobile is the target platform for the VSO Rest APIs also web solutions can be enriched with VSO functionality or integration with SharePoint and Office 365 are interesting platforms. See the image below, where build information, team activities and member licenses are integrated in an O365 team portal. See this post:Integrate Azure, Visual Studio Online and Office 365 with VSO Rest APIs. 

clip_image023

Add comment


Şarkı Sozleri