Environment Approvals & Checks documentation is very vague

Hi,

The documentation is not clear about what are the Check Configurations and what is the Approval where and how they're used what is common and in what details are they different. What I have done is that I have created via Azure DevOps 3 things: Approval, Branch Control and ExclusiveLock. I was able to get them via rest API. Also I was able to use rest API to create them. When it was required for us to update checks it got very confusing. I can't understand why approvals have different rest API endpoint for update which is described here https://docs.microsoft.com/en-us/rest/api/azure/devops/approvalsandchecks/approvals/update?view=azure-devops-rest-6.1

I was able to use https://docs.microsoft.com/en-us/rest/api/azure/devops/approvalsandchecks/check%20configurations/update?view=azure-devops-rest-6.1 endpoint to update an approval.

I still not clear if the Approvals which are described here https://docs.microsoft.com/en-us/rest/api/azure/devops/approvalsandchecks/approvals?view=azure-devops-rest-6.1 and approvals which I can be created using Add endpoint in Check Configuration is the same thing?

The Approval model is very similar to the one I receive when I get list of checks. But this one which I receive has a property settings while the one which is described in approvals has no settings and has all fields defined on the Approval object itself.

Here're the json example of the approval I get after I created 3 checks via portal. It is very very similar to https://docs.microsoft.com/en-us/rest/api/azure/devops/approvalsandchecks/approvals/update?view=azure-devops-rest-6.1#approval but different in regards to settings property.

{
    "settings": {
      "requesterCannotBeApprover": true,
      "approvers": [
        {
          "displayName": "AUser",
          "id": "136a77b2-f17b-6205-9231-5be554dd5d69",
          "uniqueName": "AUser@company.com",
          "imageUrl": "/ACompanyOrganizationName/_apis/GraphProfile/MemberAvatars/aad.aad-some-id",
          "descriptor": "aad.aad-some-id"
        }
      ],
      "executionOrder": "anyOrder",
      "minRequiredApprovers": 0,
      "instructions": "Instructions to approvers (optional)",
      "blockedApprovers": []
    },
    "createdBy": {
      "displayName": "AnotherUser",
      "id": "some-guid",
      "uniqueName": "AnotherUser@company.com",
      "descriptor": "aad.aad-some-id"
    },
    "createdOn": "2021-01-28T22:45:32.0724758Z",
    "modifiedBy": {
      "displayName": "AnotherUser",
      "id": "some-guid",
      "uniqueName": "AnotherUser@company.com",
      "descriptor": "aad.aad-some-id"
    },
    "modifiedOn": "2021-01-28T22:45:32.0724758Z",
    "timeout": 41760,
    "_links": {
      "self": {
        "href": "https://dev.azure.com/ACompanyOrganizationName/some-project-guid/_apis/pipelines/checks/configurations/11?%24expand=1"
      }
    },
    "id": 11,
    "type": {
      "id": "8c6f20a7-a545-4486-9777-f762fafe0d4d",
      "name": "Approval"
    },
    "url": "https://dev.azure.com/ACompanyOrganizationName/some-project-guid/_apis/pipelines/checks/configurations/11?%24expand=1",
    "resource": {
      "type": "environment",
      "id": "1943",
      "name": "ak-test-env"
    }
  }

MicrosoftDocs / vsts-rest-api-specs

Environment Approvals & Checks documentation is very vague #460