This API provided by Microsoft provides a reliable and well documented solution to automating Azure DevOps (ADO) functionality. In our case it is most useful for pipelines that run on continuous integration (CI) events, such as a commit or pull request. Or, in gaining insight into the state of a team in an ADO organisation.
\nThis guide is for someone without much experience using APIs like myself when I started here. The sections are based on a certain piece of functionality, not a section of the API.
\nHopefully you will enjoy using the API it as much as I did 😎
\nLanguage
\nIt is reccomended that you use Powershell or BASH for performing API requests as they are the two scripting languages that are default on Windows and Linux runners respectively. Also, they are easy to test on your local machine when diagnosing your own probelms or those of other team members. The other option that comes pre-installed on Github's runners is Python. This is just as good for sending requests, however you may prefer to develop pipelines in one language instead of swapping for scripts and skeleton code in YAML configurations.
\n\n\n\nThe ADO API uses OAuth 2.0 bearer tokens for authenticating requests. Tokens should not be confused with keys/certificates which are verified with cryptographic methods. Tokens are like passwords except that they are regularly changed and passed to different bearers. ADO refers to these tokens as Personal Access Tokens (PAT) and you can create them through the web interface as shown below:
\n1. Find the User settings icon at the top right of the page.
\n2. From the drop down, select Personal access tokens.
\n3. On the next page, select New token.
\n4. You should set the token to expire at the end of the current semester (90 days works well for this).
\n5. For good security the token should have as little privileges as possible. Below is the selection used for the pull request automation pipeline. It only needs to create work items.
\nThe body of the request is a JSON Patch and must include the operation op, path path, value value. In this case the operation is always add and the path is a directory like representation of the field.
\n","urlObject":{"query":[{"key":"ORGANISATION","value":"redbackoperations"},{"key":"PROJECT","value":"Cybersecurity"},{"key":"TEAM","value":"SecDevOps"},{"description":{"content":"For this specific use of the API there was a lot of version compatability. Make sure to check if there are any changes in Microsoft's documentation before creating your own requests.
\n","type":"text/plain"},"key":"API_VERSION","value":"7.1"},{"description":{"content":"This tells Azure DevOps not to notify the person that the task is assigned to. This is ideal so that reviewers are not flooded with pull request notifications. Instead they are all contained in one central location.
\n","type":"text/plain"},"key":"NOTIFY","value":"supressNotifications={true}"},{"description":{"content":"Your options for this field vary based on which process type you have selected for your project. For example Agile, Scrum, CMMI.
\n","type":"text/plain"},"key":"TYPE","value":"task"}],"variable":[]}},"response":[],"_postman_id":"0310e111-39a1-4cc9-b124-96066a2328fe"}],"id":"f89e7c41-01d6-4e7b-a831-4def3176f2cc","description":"The foundation for the pull request task automation is the work item section of the API. It is an HTTP POST operation which includes pretty much every field you could need except for task comments (requires subsequent requests).
\nIt uses the /wit/workitems/ area of the API.
\n","_postman_id":"f89e7c41-01d6-4e7b-a831-4def3176f2cc"}],"event":[{"listen":"prerequest","script":{"id":"8928bf20-740c-4901-8448-94e11ddbca45","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"905951e3-2301-4612-8b4a-1d8af8821abe","type":"text/javascript","exec":[""]}}],"variable":[{"key":"baseUrl","value":"https://farming-simulator.pstmn.io","disabled":true},{"key":"token","value":"T0K3N","type":"string","disabled":true}]}