Discovering VSTS APIs

Building on our current theme of Visual Studio Team Services (VSTS) API calls, let’s take a look at discovering what APIs are available.

The likely starting point for figuring out VSTS APIs is the REST API Reference for VS Team Services and TFS. Here you can view the various information and examples for the APIs currently exposed by VSTS (and TFS). The APIs are broken out into major categories with each category including links to the various resources provided by their respective APIs as shown in the excerpt below:

If you’re like me, however, you might enjoy viewing the available APIs just a little bit closer to the “metal”. This is relatively simple with VSTS because Microsoft has implemented the HTTP OPTIONS method. While you wouldn’t necessarily want to use the OPTIONS method to programmatically build and call API URLs on-the-fly (you can read more about why you might not want to do this here) that doesn’t meant it isn’t a great mechanism for spelunking around a set of APIs to see what’s offered.

To show this in action, let’s go back to our trusty web debugger, Fiddler, and execute the following HTTP command:

OPTIONS https://moonspace.visualstudio.com/DefaultCollection/_apis?api-version=2.0

Be sure to replace “moonspace” with your VSTS account name and include the Authorization header as shown in Personal Access Tokens and VSTS APIs.

At the time of writing this article the OPTIONS method returns 281 entries.

The screen shot above shows the first item expanded. For easier searching and navigation I recommend copying the JSON results to a full-featured editor, such as Visual Studio Code or Visual Studio.

If you’re using Visual Studio Code, save the file with a “.json” extension and press SHIFT+ALT+F to format the JSON into something more readable. In Visual Studio 2015, paste the unformatted JSON into a file with a “.json” extension and Visual Studio will format it for you.

To get a general idea of the information that is being returned in the JSON search for “Definitions” until you come across an entry like the following:

The above entry matches up with the API to return a list of build definitions as defined in the official API documentation here.

Let’s take a quick look at a few things in the above screen shot:

• The area lets us know which API “category” we are dealing with. In this case, we are looking at an API that has something to do with Build(s).
• The resourceName let’s us know what “subcategory” (resource) we are dealing with. In this case, we are looking at an API that has something to do with Build Definitions.
• The routeTemplate provides us with a template that we can use to build an API call that interacts with the resources specific to this API (build definitions).

To play this out a bit, let’s take the above route template and combine it with what we already know. The bold sections of the URL below are taken from the information shown above:

https://moonspace.visualstudio.com/DefaultCollection/Test%20Project/_apis/build/definitions?api-version=2.0

In my case, executing an HTTP GET with the above URL returns a list of four build definitions. The first build definition in my results just happens to have an ID of 1. Based on the route template shown above I should then be able to add “/1” to my URL and get details specific to this build definition. For example:

https://moonspace.visualstudio.com/DefaultCollection/Test%20Project/_apis/build/definitions/1?api-version=2.0

Executing an HTTP GET with this modified URL will return the details of everything that makes up this specific build definition:

Just to be clear, you could get most, if not all, of this information from the on-line API documentation. However, sometimes it’s enlightening to see how the sausage is made because it has the potential to lead to a better understanding of how the APIs are created and/or related to each other. You also might just see something that you would have otherwise missed.

Happy spelunking!