API for the Azure DevOps Team Calendar
Table of Contents
Azure DevOps has an extension that provides a calendar for each Team, but the API is not documented. These notes cover API methods for the Team calendar, to enable automation.
Installing The Team Calendar #
Add the Azure DevOps Team Calendar from the Marketplace to your organization in Azure DevOps.
URL Format #
To access a calendar, you must build a URL that specifies your Azure DevOps organization, the teamId of the Team, and the month and year that are relevant for the operation:
https://extmgmt.dev.azure.com/{organisation}/_apis/ExtensionManagement/InstalledExtensions/ms-devlabs/team-calendar/Data/Scopes/Default/Current/Collections/{teamId}.{monthNumber}.{year}/Documents
You must include an API version with calls that create, update or delete a calendar event:
https://extmgmt.dev.azure.com/{organisation}/_apis/ExtensionManagement/InstalledExtensions/ms-devlabs/team-calendar/Data/Scopes/Default/Current/Collections/{teamId}.{monthNumber}.{year}/Documents?api-version=6.1-preview.1
API Calls #
You access the calendar resources through the Azure DevOps REST API.
GET Calendar Events #
Issue a GET request on the main URL:
https://extmgmt.dev.azure.com/{organisation}/_apis/ExtensionManagement/InstalledExtensions/ms-devlabs/team-calendar/Data/Scopes/Default/Current/Collections/{teamId}.{monthNumber}.{year}/Documents
This returns a document with this structure:
{
"count": 1,
"value": [
{
"category": "Uncategorized",
"description": "",
"endDate": "2021-02-03T00:00:00Z",
"startDate": "2021-02-03T00:00:00Z",
"title": "Example event 1",
"__etag": 1,
"id": "f14fd3ff-f39b-4d23-a353-6e3dfbf3af4a"
}
]
}
A month with no events will return a document with this structure:
{
"count": 0,
"value": []
}
PUT New Calendar Event #
Send a JSON document with this structure:
{
"category": "Uncategorized",
"description": "",
"endDate": "2021-03-01T00:00:00Z",
"startDate": "2021-03-01T00:00:00Z",
"title": "Example event 21"
}
PUT Update Calendar Event #
To delete a calendar event, send a HTTP PUT request. This is the format of the JSON document:
{
"__etag": 3,
"id": "290d0223-0256-432d-9c18-a6fed6e8b5e3",
"category": "Uncategorized",
"description": "",
"endDate": "2021-02-01T00:00:00Z",
"startDate": "2021-02-01T00:00:00Z",
"title": "Example event 1"
}
Note that this includes the id of the calendar, and an __etag value. Always set the __etag value as the current __etag value of the event, plus one. The Data Storage that Team Calendar uses relies on the etag value for locking.
DELETE Calendar Event #
To delete a calendar event, send a HTTP DELETE request to a URL that includes the ID for the event:
https://extmgmt.dev.azure.com/{organisation}/_apis/ExtensionManagement/InstalledExtensions/ms-devlabs/team-calendar/Data/Scopes/Default/Current/Collections/{teamId}.{monthId}.{year}/Documents/{eventId}?api-version=6.1-preview.1
This returns a HTTP 204 response, with an empty body.
Error Structure #
Errors return a JSON document with this structure:
{
"$id": "1",
"innerException": null,
"message": "%error=\"1660000\";%:The document already exists",
"typeName": "Microsoft.VisualStudio.Services.ExtensionManagement.WebApi.DocumentExistsException, Microsoft.VisualStudio.Services.ExtensionManagement.WebApi",
"typeKey": "DocumentExistsException",
"errorCode": 0,
"eventId": 3000
}
Resources #
- Azure DevOps Team Calendar
- Team Calendar GitHub project
- Team Calendar uses Data Storage
- How to integrate an Azure Devops Calendar into Outlook - The answer here from Starian Chen was the start of this work