Azure Devops REST API documentation for policies is missing?

Question

We're building a web based self service for our employees, to speed up/improve everyones DevOps experience. The self service utilizes the Azure Devops REST API and most of it works fine but as I'm about to implement the branch policies I get stuck for lack of documentation (or my inability to find it).

I think I have found what documentation is available for creating policy configurations, like this article. There's just a general mention of "settings" needs to be a JObject and then seven examples for various scenarios but if there are any reference articles for the 14 supported policy types then I have missed it.

Am I just blind or did Microsoft just not bother with documenting how to form the JObjects for the different kinds of configurations?

My guess is they are doing something with decoration on the API that self-generates the documentation. Since the settings is kind of generic holder, they were probably documenting some of the options with what you noted. They have added some options so probably isn't complete. The UI will leverage these same API ... so I usually just inspect network traffic for the individual settings I care about. — Matt
I think you're right. It's pretty sloppy from Microsoft, though. — Jonas Rembratt

Leo Liu-MSFT Leo Liu-MSFT · Accepted Answer · 2020-12-03T09:43:48

Azure Devops REST API documentation for policies is missing?

For me, I am more inclined that the document does not explicitly point out the content of JObject.

When we check that REST API document Configurations - Create, we could get following info:

Indeed, it only states that its type is a JSON object without specific content or examples.

To get the content of this JSON object, I use the REST API Configurations - Get to get the content of the Response body, I could get following response body:

        "settings": {
            "minimumApproverCount": 2,
            "creatorVoteCounts": false,
            "allowDownvotes": false,
            "resetOnSourcePush": false,
            "requireVoteOnLastIteration": false,
            "resetRejectionsOnSourcePush": false,
            "blockLastPusherVote": false,
            "scope": [
                {
                    "refName": "refs/heads/Dev",
                    "matchKind": "Exact",
                    "repositoryId": "dcb40ef6-dae0-4e3c-b581-2f71c76e09a6"
                }
            ]
        },

So, we could to know the content is indeed a JSON object and it will be different due to the different policies we set.

Now, we move back to the samples in that document, we could find that there are many such settings, like:

Approval count policy:

{
  "isEnabled": true,
  "isBlocking": false,
  "type": {
    "id": "fa4e907d-c16b-4a4c-9dfa-4906e5d171dd"
  },
  "settings": {
    "minimumApproverCount": 1,
    "creatorVoteCounts": false,
    "scope": [
      {
        "repositoryId": null,
        "refName": "refs/heads/master",
        "matchKind": "exact"
      }
    ]
  }
}

If we want to set any other supported policy types, we can manually set it on the UI, and then get the corresponding response body about it.

Azure Devops REST API documentation for policies is missing?

1 Answers