Skip to main content

Explore the API

To find the right way to start and creating new cmdlets is not easy when you start. But there are basically two approaches you might want to use.

Use Postman​

To access the REST API, you are going to need a Personal Access Token (PAT). You can learn how to create a PAT from the Authenticating with personal access tokens topic of docs.microsoft.com. Once you have a PAT start Postman. If you do not have Postman you can download it from getPostman.com.

I normally begin with Get-xxx function of any API. For the purpose of this document I am going to use the User Entitlements API. This function will combine the Get and List APIs. I will begin with List. Using the sample request enter the data into Postman.

GET 'https://vsaex.dev.azure.com/{organization}/_apis/userentitlements?top={top}&skip={skip}&api-version=5.1-preview.2'

Replace {organization} with just the portion of your Azure DevOps (AzD) URL after "https://dev.azure.com" For {top} I am going to enter 100 and for {skip} 0. Postman should look similar to the image below.

Postman Get Request

Now before we press Send we have to enter our PAT. Select "Basic Auth" for Type under Authorization. You can leave the Username empty. For your Password copy and paste in your PAT.

Postman Auth

Now you can press Send. Postman will issue the request and display the results at the bottom of the user interface.

Postman Auth

This confirms that we know how to build a complete request to the service. This is an opportunity to explore all the parameters of the API and make sure you know what to expect.

Use Invoke-VSTeamRequest​

The most powerful function in VSTeam is Invoke-VSTeamRequest. If a commandlet does not exist (yet) you can use this command to test new implementations against the API.

The function uses completer for the parameters area and resource queries the API to get all possible values. In that way you get easily test API endpoints directly with VSteam and either start scripting or go from there to start writing a new commandlet for VSTeam or VSTeam Plus.

To use the completer functionality if the cmdlet you need to login with a PAT to an organization

Set-VSTeamAccount -Account MyOrg -PAT MyPat

And then you can do the following

Animation showing Invoke-VSTeamRequest example

As you can see, the -resource parameter is contextual and shows only values that fit with the -area parameter. This might make it easier for you to test a not yet existing API implementation.

A full call could look like this

Invoke-VSTeamRequest -area 'wit' -resource 'queries' -version '6.0' -ProjectName 'MyProject'