In this post, Senior Application Development Managers Art Garcia demonstrates how to navigate the VSTS REST APIs.

Visual Studio Team Services or VSTS has matured into one of the leading Application Lifecycle management tools available. It allows you to not only manage your work and team velocity, but it also is a great tool to use in building and deployment as well. If you have several projects both current and future, the setup and administration can sometimes be a challenge. You want to make sure all projects have certain team’s setup and some basic build and release artifacts. This will make transitioning from one project to another seamless and make for a consistent experience.

So therein lies the problem. I have multiple project I need to create and assign users and teams to. Fortunately, VSTS has a rich array of REST API’s to help. Everything from creating a project to adding work items and almost everything in between. For this discussion we will cover adding a project, adding teams to the project and finally adding users to the teams. We will also cover adding account level groups as well. So, let’s get started.

The place you will spend most of your time will be the VSTS REST API documentation. Here is where you will find the REST calls to manage VSTS. We will start with the Project and Teams.

Here you navigate to the Create a team project. As with many of the REST calls in VSTS, it’s not just one call to get what you are after. For the create project you will run the following POST operation.

POST https://{instance}/defaultcollection/_apis/projects?api-version={version}

The {instance} is your VSTS account i.e. myaccount.visualstudio.com, the version is the latest version of the API which is found in the documentation for the API. You will need to add the request for this operation and here is where it gets interesting. The request for this is as follows: The first few, name, description and what source control type are straight forward. The process template is the one that will take another call. You need the GUID of the process you want to use. Agile, Scrum, CMMI, or any custom process in your account has a unique identifier. We need that GUID here in the request. Fortunately, that’s an easy call to the API.

GET https://{instance}/DefaultCollection/_apis/process/processes?api-version={version}

This will give you a list of processes. You can filter them by name to find the process you are looking for. Here is some PowerShell to find the process.

$projectUri = "https://" + $VSTSMasterAcct + ".visualstudio.com/DefaultCollection/_apis/process/processes?api-version=1.0"

$returnValue = Invoke-RestMethod -Uri $projectUri -Method Get -ContentType "application/json" -Headers $authorization

$id = ($returnValue.value).Where( {$_.name -match “Agile” })

return $id.id

Now you just replace the process id in the request and you are ready to create your project. Below is a snapshot of my CreateVSTSProject PowerShell function. If you notice on line 17, I call GetVSTSProcesses and pass in my $userParams. This is a small JSON text that contains the project name, and a few more parameters I need for my code to run.

The parameter file looks like this. I reference this file throughout my scripts, so I can change things easily in one place.

I also check if the project exists, if it does the API will throw an error. I capture that error and return that the project exists.

Ok, so now we have a valid Project in VSTS, now let’s add some teams and Groups to the project. To do this we will make a call to an API in the same Project and Team family. The Create a Team REST call is as follows and the documentation can be found here.

POST https://{instance}.VisualStudio.com/DefaultCollection/_apis/projects/{project}/teams?api-version={version}

The {instance} is your vsts account i.e.. myaccount.visualstudio.com, the version is the latest version of the API which is found in the documentation for the API. The Project is the name of the project you want to add these teams to. The request for this is simple, just a name and description as shown below. Here is what the code looks like:

This will give you teams in the project you just created. These are teams only visible in the project you created. If you want to have a team span multiple projects, then you would create a group at the account level. This will require using the Graph REST API. A word of caution here. As of this writing this API is in an Alpha preview. Really that just means it’s not completely baked yet. They are still working out the usage patterns and hardening the code. That said, I still encourage you to use them, just remember if you find an issue, report it. That way we all benefit.

So to add groups with the Graph API at the account level you will run the following REST call.

POST https://{instance}/_apis/graph/groups?api-version={version}

The request for this call is very straight forward, just the displayName and the description as seen below. This call will either create a new account level group and return the group information or just return the group information from an existing group. Either way you get the group information. The code to add a VSST account level group is shown below

So at the beginning of this blog I said I would create a project, add teams and account level groups. The only part missing is adding users to those groups and teams. This is actually very easy. All that’s required is a simple Graph REST call. Again, as before, be forewarned, this API is in Alpha preview.

So the code to add users to a group or team is as follows.

If you look closely, you see that this call is asking for the Group descriptor. So, remember when we discussed adding an account group? I mentioned that it would return the group information. One important part of that return is the group descriptor. You will need this to find the appropriate group to add users to. Once you have that it’s a matter of adding the user’s email in the request as shown in the code example.

So that’s a lot of information to digest. Believe me it took me a bit to wrap my head around the API and all its capable of. These API’s are a wonderful way to automate and standardize many VSTS functions and manual tasks. What I have shown is just the beginning. Now we have the project, the teams and the users in the teams or groups. What about a build script or a release definition or maybe adding some standard work items? All are possible with the API.

I trust this has given you a small glimpse into what is possible with the API. The next entry in the series will be adding a build and release to the project you just created. Then we will tackle the security. Securing the teams and groups to allow or deny what operations can be performed. That’s where it gets interesting. In my upcoming post, I will demonstrate the VSTS REST APIs to secure Team Projects.

Get the source from this article on GitHub here.

Premier Support for Developers provides strategic technology guidance, critical support coverage, and a range of essential services to help teams optimize development lifecycles and improve software quality.  Contact your Application Development Manager (ADM) or email us to learn more about what we can do for you.