Planning API

The Minddistrict REST API offers endpoints for accessing the planned events for a client or for a friend, such as future tasks for diaries. The planning API can be used by the API consumer to remind the user about the available task at the time of the task.

Discovering a user’s planned events

To discover the URLs for accessing a user’s planned events, send a GET request to the URL of a client or a friend and look for the @links metadata. The following links will be available:

Description of the planning links discoverable via a client, a friend or via a planning

Name

URL for

in user @links

in planning @links

planning

The planning endpoint which reports metadata about the user’s planned events.

planning.ics

ics

Retrieve all planned events as ICS.

View planned events as a calendar

You can retrieve the planned events defined for a user as an ICS calendar.

Example request:

GET /api/2/c/cb7bae66c0104b15ac661931811fe365/planning/ics HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABfxfsnijSVf9Tfcer0JhzekIF--SYw4ckwGJXCHGVX6LJAEZkTj6HOs3gGH8OsvcZ4PLSJp-x68spXU3S0xKlEvN5U5ECJx4EdyV7mQUOOhtxfyXfI5wHbL0x3KvizNUMGkFwYgsUvWLMZg7WVvvCuyH_XMlA3LLK4Rvmel0ZRR4CSJ_D1sOCblhrx6Ku3wHmKoeiE

The response will be an ICS description of the planning:

HTTP/1.0 200 Ok
Cache-Control: max-age=0, no-cache, no-store, must-revalidate
Content-Length: 435
Content-Type: text/calendar;charset=utf-8

BEGIN:VCALENDAR
VERSION:2.0
PRODID:Minddistrict ITH
BEGIN:VTODO
CATEGORIES:diary
DTSTAMP;VALUE=DATE-TIME:20201201T081329Z
DTSTART;TZID=Europe/Amsterdam;VALUE=DATE-TIME:20150101T100000
RRULE:FREQ=DAILY;INTERVAL=1
SUMMARY:It is time to fill in your diary "Moment"!
UID:0-cb7bae66c0104b15ac661931811fe365-p.1@customer.minddistrict.com
X-MD-DIARY:http://ns.minddistrict.com/diary/schema/entry#moment:1
END:VTODO
END:VCALENDAR

In this example one event “Moment” is defined for every day at 10:00 after the 1st of January 2015. The date and time of the events and their repetition patterns are local to the timezone of the application. The timezone identifiers are taken from the Olson database; most ICS parsing libraries will recognize these identifiers.

The file is made up of VTODO components; a single VTODO can represent a single planned event, or a series of events that repeat according to some rule (“Every Tuesday and Thursday at 09.00”). The structure of a VTODO component will match the definition you can find in the ICS standard, and the file should be compatible with any calendar software which understands that standard. API consumers who wish to iterate over planned events are encouraged to use the libical library to parse the file, as this is what the API output is tested against.

Description of expected ICS properties for a todo item

Property

Definition

DTSTAMP

Date and time of the last modification

DTSTART

Date and time of the scheduled event, or the first in the sequence if there is a recurrence rule.

SUMMARY

Title of the event

CATEGORIES

A comma-separated list of event category names. Can be diary, training or plan.

RRULE

Optional repetition rule

Types of planned events

The type of event is indicated in the CATEGORIES property. At present there is only one category (diary) however as we anticipate adding others, you are encouraged to filter on the category explicitly to ensure forward-compatibility.

A diary todo is a reminder for the user to fill in a particular diary. The SUMMARY will contain a string suitable for display to the user (for example It's time to fill in your diary).

View planned events as JSON

With the items endpoint you can fetch planned events in JSON. Repetition is computed and every single event is listed. This requires you to provide both a start date (after) and an end date (before) while listing them, since some events can be repeated without an end date.

An event is serialized with the following information:

Name

Value

Explanation

Value type

Notes

title

Title

-

String

topic

Topic

-

String

Required
description

Description

-

String

Required, Read-only
visible

Visible

-

Boolean

Required, Read-only
eta

Estimated time of arrival

-

Date with time

Required

The @type meta information for this object is: http://ns.minddistrict.com/todo.

For instance this fetches events in the first 7 days of 2019:

GET /api/2/c/cb7bae66c0104b15ac661931811fe365/planning/items?after=2019-01-01&before=2019-01-07 HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABfxfsnijSVf9Tfcer0JhzekIF--SYw4ckwGJXCHGVX6LJAEZkTj6HOs3gGH8OsvcZ4PLSJp-x68spXU3S0xKlEvN5U5ECJx4EdyV7mQUOOhtxfyXfI5wHbL0x3KvizNUMGkFwYgsUvWLMZg7WVvvCuyH_XMlA3LLK4Rvmel0ZRR4CSJ_D1sOCblhrx6Ku3wHmKoeiE

The result is the list of events:

HTTP/1.0 200 Ok
Cache-Control: max-age=0, no-cache, no-store, must-revalidate
Content-Length: 2394
Content-Type: application/json;charset=UTF-8

{
    "@items": [
        {
            "@type": "http://ns.minddistrict.com/todo",
            "@url": "https://customer.minddistrict.com/api/2/c/cb7bae66c0104b15ac661931811fe365/planning/p.1/t.1461",
            "description": "From Jan 1, 2015 every day at 10:00 AM",
            "eta": "2019-01-01T09:00:00",
            "title": null,
            "topic": "Moment",
            "visible": true
        },
        {
            "@type": "http://ns.minddistrict.com/todo",
            "@url": "https://customer.minddistrict.com/api/2/c/cb7bae66c0104b15ac661931811fe365/planning/p.1/t.1462",
            "description": "From Jan 1, 2015 every day at 10:00 AM",
            "eta": "2019-01-02T09:00:00",
            "title": null,
            "topic": "Moment",
            "visible": true
        },
        {
            "@type": "http://ns.minddistrict.com/todo",
            "@url": "https://customer.minddistrict.com/api/2/c/cb7bae66c0104b15ac661931811fe365/planning/p.1/t.1463",
            "description": "From Jan 1, 2015 every day at 10:00 AM",
            "eta": "2019-01-03T09:00:00",
            "title": null,
            "topic": "Moment",
            "visible": true
        },
        {
            "@type": "http://ns.minddistrict.com/todo",
            "@url": "https://customer.minddistrict.com/api/2/c/cb7bae66c0104b15ac661931811fe365/planning/p.1/t.1464",
            "description": "From Jan 1, 2015 every day at 10:00 AM",
            "eta": "2019-01-04T09:00:00",
            "title": null,
            "topic": "Moment",
            "visible": true
        },
        {
            "@type": "http://ns.minddistrict.com/todo",
            "@url": "https://customer.minddistrict.com/api/2/c/cb7bae66c0104b15ac661931811fe365/planning/p.1/t.1465",
            "description": "From Jan 1, 2015 every day at 10:00 AM",
            "eta": "2019-01-05T09:00:00",
            "title": null,
            "topic": "Moment",
            "visible": true
        },
        {
            "@type": "http://ns.minddistrict.com/todo",
            "@url": "https://customer.minddistrict.com/api/2/c/cb7bae66c0104b15ac661931811fe365/planning/p.1/t.1466",
            "description": "From Jan 1, 2015 every day at 10:00 AM",
            "eta": "2019-01-06T09:00:00",
            "title": null,
            "topic": "Moment",
            "visible": true
        }
    ],
    "@links": []
}

View planning metadata

To view the list of endpoints accessible for a planning, send a GET request to the planning URL. This URL is discoverable in the @links metadata of

under the name planning.

Example request:

GET /api/2/c/cb7bae66c0104b15ac661931811fe365/planning HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABfxfsnijSVf9Tfcer0JhzekIF--SYw4ckwGJXCHGVX6LJAEZkTj6HOs3gGH8OsvcZ4PLSJp-x68spXU3S0xKlEvN5U5ECJx4EdyV7mQUOOhtxfyXfI5wHbL0x3KvizNUMGkFwYgsUvWLMZg7WVvvCuyH_XMlA3LLK4Rvmel0ZRR4CSJ_D1sOCblhrx6Ku3wHmKoeiE

The response will be the corresponding meta information:

HTTP/1.0 200 Ok
Cache-Control: max-age=0, no-cache, no-store, must-revalidate
Content-Length: 493
Content-Type: application/json;charset=UTF-8

{
    "@links": [
        {
            "name": "ics",
            "url": "https://customer.minddistrict.com/api/2/c/cb7bae66c0104b15ac661931811fe365/planning/ics"
        },
        {
            "name": "items",
            "url": "https://customer.minddistrict.com/api/2/c/cb7bae66c0104b15ac661931811fe365/planning/items"
        }
    ],
    "@type": "http://ns.minddistrict.com/planning",
    "@url": "https://customer.minddistrict.com/api/2/c/cb7bae66c0104b15ac661931811fe365/planning"
}