Azure-devops-docs: Invoke Rest API documentation

[timwebster9]

Where to start with this...

I was trying to figure out how to call the Azure Management API with this task (not to be confused with API Management Service), and I figured it out eventually with trial and error. Things that I think could have helped:

This is aimed at the YAML documentation.

• Maybe this is obvious to long-time users of VSTS, but it's not at all clear from the documentation what the different connection types offer, and how they are different. connectedServiceName requires a 'generic service connection' that requires you to specify an endpoint URL. connectedServiceNameARM can use a service principal and handle the authentication (I only knew this because I use these types of service connections for other tasks). But then there is nowhere to put an endpoint URL. How is one to know what URL it is using? Sure, there is urlSuffix, but what about the rest of it? On a hunch I filled in the urlSuffix with the path to the Management API service I wanted, hoping it was calling https://management.azure.com, and sure enough it was.

• connectionType, serviceConnection, and azureServiceConnection aren't mentioned in the 'Arguments' section, although they are in the example YAML snippet.

• The docs say that Generic endpoint is required. There is no YAML parameter in the example called anything resembling generic endpoint. Does it even exist?

• It says Completion event is required. I didn't use it and it didn't complain. It also says that 'API response' is the default. How can it have a default when it is required?

• It says Method is required. Again I didn't specify and it didn't complain. Is POST the default, and that's why it's in the example snippet? I suspect it is, because the service I needed to invoke (applynetworkconfigurationupdates) requires a POST and it worked.

• waitForCompletion isn't mentioned in the 'Arguments' section, although it's in the YAML snippet.

The task itself is great, but these docs need an overhaul...

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 89bc6da4-5a1e-5989-f4f0-27465953b5fd
• Version Independent ID: fd12f976-5d3b-3b1b-3d0a-a0bf2a60c961
• Content: Invoke HTTP REST API task - Azure Pipelines & TFS
• Content Source: docs/pipelines/tasks/utility/http-rest-api.md
• Product: devops
• GitHub Login: @alexhomer1
• Microsoft Alias: ahomer

[alexhomer1]

Thank you for your feedback. I will pass this on to the product team and update the topic based on their response.

[RoopeshNair]

@shashban

[burybury]

Same Problem here

[shashban]

Thanks. We'll update the documentation.
To invoke Azure management APIs, you can provide Azure ARM connection input and specify urlSuffix to append to https://management.azure.com and form the complete call.

[burybury]

yeah ive figured that out. should have been in the doc ;)

[JamesMiera]

Documentation seems largely unusable. It certainly does not survive contact with actual users.

[mchelen]

This is very confusing. Can someone provide an example of how to do a simple REST query to Google.com?

[zandmeister]

same here, I am trying to use this task to make a call to login.microsoftonline.com using oauth2 and get an access token in response, but I have no clue about where should I add the scope(in the body or headers?) of the call or how to store the token (if i get any)