The request URI form is given as:
VERB https://{instance}[/{collection}[/{team-project}]/_apis[/{area}]/{resource}?api-version={version}
The [/{collection}[/{team-project}]
part is incorrect and ambiguous. The square bracket [
to indicate optional parts of the URL is not closed properly. There are two opens but only one closed.
The examples in some of the other sections show it as:
DELETE https://{accountName}.visualstudio.com/{project}/_apis/test/Plans/{planId}/suites/{suiteId}?api-version=5.0-preview.3
or, like so:
curl -u {username}[:{personalaccesstoken}] https://{account}.VisualStudio.com/DefaultCollection/_apis/projects?api-version=2.0
...which indicates that it's meant to be {collection}
or {team-project}
ie. the 2nd [
should actually be a pipe |
(however, see last example below):
VERB https://{instance}[/{collection}|/{team-project}]/_apis[/{area}]/{resource}?api-version={version}
Otherwise, it could be interpreted as allowing URI's with both collection and team-project:
DELETE https://fabrikam.visualstudio.com/DefaultCollection/fabrikam-fiber-tfvc/_apis/test/Plans/1/suites/8?api-version=5.0-preview.3
And since exactly one of them is necessary and both can't be skipped, it should be:
VERB https://{instance}/({collection}|{team-project})/_apis[/{area}]/{resource}?api-version={version}
(or, since the parentheses could be misinterpreted for literals)
VERB https://{instance}/{collection|team-project}/_apis[/{area}]/{resource}?api-version={version}
Also, update the docs' collection:
section to specify that it's exactly either one but not both. To me, it was unclear until I saw examples for 'DefaultCollection' vs '{project}'.
Document Details
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.