API for the Azure DevOps Team Calendar

automation, devops
Page content

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