API for the Azure DevOps Team Calendar
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
It seems that it will accept any version but the query string for api-version must include the string -preview.
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