Diary API

The Minddistrict REST API offers endpoints for accessing and posting entries in the diary of a client or a friend (for those who have a diary configured).

Definition

A diary is composed of a collection of entries. Each entry is defined by a list of fields. The exact fields to appear in an entry are defined by a professional inside the Minddistrict platform, and exported via the API as a schema so that API consumers can read and work with diary entries. The schema may provide additional information on how to present the entry to the end-user.

The entry is transferred as a json object, where each attribute is a field declared in the schema.

The list of schemas that may be used in a particular diary is that diary’s configuration. Each entry in the diary can have a different schema (from the configuration). Because of this, when retrieving one or multiple entries, an extra metadata field @schemas will be available, listing the schemas for the entries contained in the response.

You can find more information about the schema for an entry here:

Discovering a user diary

To discover the URLs for accessing a user’s diary, send a GET request to the URL of a client or a friend and look for the @links metadata. (The client and friend endpoints are convenient central points for discovering all endpoints that are specific to a single user, so you’ll also see links that are not diary-related; the diary-specific URLs can also be found in the @links metadata of the diary itself.) If the user has access, the following links will be available:

Description of the diary links discoverable via a client/friend or via a diary

Name

URL for

…in user @links

…in diary @links

diary

The diary endpoint which reports metadata about the client’s diary.

diary.configuration

configuration

Listing the available entry schemas.

diary.entries

entries

Creating a new entry.

diary.entries.items

entries.items

Listing existing entries.

If the user does not have access to a diary these links will not be present in the client or friend request response.

Note

While you can probably guess these URLs from their names, we recommend you use the discovery mechanism rather than concatenating strings to generate the URLs your application will access. We do not guarantee that the URL structure will be predictable (e.g. we may choose to serve some resources from different locations for performance reasons), but you can always trust the URLs reported in @links.

View diary entries

To view the list of entries for a specific diary send a GET request to the diary.entries.items URL. This URL is discoverable in the @links metadata of

  • a client or friend under the name diary.entries.items;

  • a diary under the name entries.items.

Example request:

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

The response will be the list of entries that that diary contains:

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

{
    "@items": [
        {
            "@changes": {
                "creation_time": "2020-12-01T08:13:29",
                "modification_time": "2020-12-01T08:13:29"
            },
            "@type": "http://ns.minddistrict.com/diary/schema/entry#moment:1",
            "@url": "https://customer.minddistrict.com/api/2/c/cb7bae66c0104b15ac661931811fe365/diary/entries/e.1",
            "dt": "2020-12-01T08:13:29",
            "picture": null,
            "text": "I am flying!"
        }
    ],
    "@links": [],
    "@schemas": [
        {
            "@id": "http://ns.minddistrict.com/diary/schema/entry#moment:1",
            "fields": [
                {
                    "name": "text",
                    "title": "Tekst",
                    "type": "text"
                },
                {
                    "name": "picture",
                    "title": "Afbeelding",
                    "type": "image"
                }
            ],
            "resources": [],
            "title": "Moment"
        }
    ]
}

To restrict the result to entries modified after a certain date use the query parameter modified_after with a date and time value:

GET /api/2/c/cb7bae66c0104b15ac661931811fe365/diary/entries/items?modified_after=2014-05-01T12:00:00 HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABfxfsnijSVf9Tfcer0JhzekIF--SYw4ckwGJXCHGVX6LJAEZkTj6HOs3gGH8OsvcZ4PLSJp-x68spXU3S0xKlEvN5U5ECJx4EdyV7mQUOOhtxfyXfI5wHbL0x3KvizNUMGkFwYgsUvWLMZg7WVvvCuyH_XMlA3LLK4Rvmel0ZRR4CSJ_D1sOCblhrx6Ku3wHmKoeiE

The response will be the list of matching entries:

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

{
    "@items": [
        {
            "@changes": {
                "creation_time": "2020-12-01T08:13:29",
                "modification_time": "2020-12-01T08:13:29"
            },
            "@type": "http://ns.minddistrict.com/diary/schema/entry#moment:1",
            "@url": "https://customer.minddistrict.com/api/2/c/cb7bae66c0104b15ac661931811fe365/diary/entries/e.1",
            "dt": "2020-12-01T08:13:29",
            "picture": null,
            "text": "I am flying!"
        }
    ],
    "@links": [],
    "@schemas": [
        {
            "@id": "http://ns.minddistrict.com/diary/schema/entry#moment:1",
            "fields": [
                {
                    "name": "text",
                    "title": "Tekst",
                    "type": "text"
                },
                {
                    "name": "picture",
                    "title": "Afbeelding",
                    "type": "image"
                }
            ],
            "resources": [],
            "title": "Moment"
        }
    ]
}

If the user does not have access to a diary, those requests will fail with a 404 Not Found HTTP status code.

View diary available schemas

To view the list of schemas for entries you can add in a diary, send a GET request to the diary.configuration URL. This URL is discoverable in the @links metadata of

  • a client or friend under the name diary.configuration;

  • a diary under the name configuration.

Example request:

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

The response will be a list of diary schemas:

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

{
    "@schemas": [
        {
            "@id": "http://ns.minddistrict.com/diary/schema/entry#emotion:6",
            "charts": [
                {
                    "buckets": "day",
                    "series": [
                        {
                            "bucket-function": "tally",
                            "field": "emotion"
                        }
                    ],
                    "title": "Frequentie van emoties per dag",
                    "type": "bar"
                }
            ],
            "fields": [
                {
                    "choices": [
                        {
                            "icon": "resources/happy.png",
                            "name": "Blij",
                            "value": "happy"
                        },
                        {
                            "icon": "resources/angry.png",
                            "name": "Boos",
                            "value": "angry"
                        },
                        {
                            "icon": "resources/sad.png",
                            "name": "Verdrietig",
                            "value": "sad"
                        },
                        {
                            "icon": "resources/scared.png",
                            "name": "Angstig",
                            "value": "scared"
                        }
                    ],
                    "name": "emotion",
                    "required": true,
                    "title": "Hoe voel jij je?",
                    "type": "choice"
                },
                {
                    "default": 1,
                    "max": 5,
                    "min": 1,
                    "name": "intensity",
                    "required": true,
                    "title": "Hoe sterk is deze emotie?",
                    "type": "integer",
                    "widget": "slider"
                },
                {
                    "description": "In welke situatie bevind jij je?",
                    "name": "situation",
                    "title": "Situatie",
                    "type": "text"
                },
                {
                    "name": "picture",
                    "title": "Afbeelding",
                    "type": "image"
                }
            ],
            "resources": [
                {
                    "name": "resources/angry.png",
                    "url": "https://cs.minddistrict.com/emotion/6/resources/angry.png"
                },
                {
                    "name": "resources/happy.png",
                    "url": "https://cs.minddistrict.com/emotion/6/resources/happy.png"
                },
                {
                    "name": "resources/sad.png",
                    "url": "https://cs.minddistrict.com/emotion/6/resources/sad.png"
                },
                {
                    "name": "resources/scared.png",
                    "url": "https://cs.minddistrict.com/emotion/6/resources/scared.png"
                }
            ],
            "title": "Emotie"
        },
        {
            "@id": "http://ns.minddistrict.com/diary/schema/entry#moment:1",
            "fields": [
                {
                    "name": "text",
                    "title": "Tekst",
                    "type": "text"
                },
                {
                    "name": "picture",
                    "title": "Afbeelding",
                    "type": "image"
                }
            ],
            "resources": [],
            "title": "Moment"
        }
    ]
}

Since the exact list of addable entries is configured by a professional inside the Minddistrict platform, different users might have access to different entry types. In addition, this list might be changed by the professional and therefore the response from the API might change over time as well.

If the user does not have access to a diary, this request will fail with a 404 Not Found HTTP status code.

Creating an entry

To create a new entry in a diary, send a POST request to the diary.entries URL. This URL is discoverable in the @links metadata of

Put the JSON encoded data for the new entry in the body of the request.:

POST /api/2/c/cb7bae66c0104b15ac661931811fe365/diary/entries HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABfxfsnijSVf9Tfcer0JhzekIF--SYw4ckwGJXCHGVX6LJAEZkTj6HOs3gGH8OsvcZ4PLSJp-x68spXU3S0xKlEvN5U5ECJx4EdyV7mQUOOhtxfyXfI5wHbL0x3KvizNUMGkFwYgsUvWLMZg7WVvvCuyH_XMlA3LLK4Rvmel0ZRR4CSJ_D1sOCblhrx6Ku3wHmKoeiE
Content-Length: 191
Content-Type: application/json

{
    "@type": "http://ns.minddistrict.com/diary/schema/entry#emotion:6",
    "dt": "2014-04-11T11:41:09.817177",
    "emotion": "happy",
    "intensity": 5,
    "situation": "I am awesome"
}

The response will return the newly created entry:

HTTP/1.0 201 Created
Cache-Control: max-age=0, no-cache, no-store, must-revalidate
Content-Length: 437
Content-Type: application/json;charset=UTF-8
Location: https://customer.minddistrict.com/api/2/c/cb7bae66c0104b15ac661931811fe365/diary/entries/e.2

{
    "@changes": {
        "creation_time": "2020-12-01T08:13:32",
        "modification_time": "2020-12-01T08:13:32"
    },
    "@type": "http://ns.minddistrict.com/diary/schema/entry#emotion:6",
    "@url": "https://customer.minddistrict.com/api/2/c/cb7bae66c0104b15ac661931811fe365/diary/entries/e.2",
    "dt": "2014-04-11T11:41:09",
    "emotion": "happy",
    "intensity": 5,
    "picture": null,
    "situation": "I am awesome"
}

A new entry is created for a specific schema, which must be one of the schemas found at the configuration endpoint for the diary. As well as the fields defined on the schema (see the fields documentation for examples), you must provide a @type value (describing which schema to use) and a dt value (the UTC date/time for the entry) when creating an entry.

Posting a diary entry without the required fields as dictated by the schema will yield an error.:

POST /api/2/c/cb7bae66c0104b15ac661931811fe365/diary/entries HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABfxfsnijSVf9Tfcer0JhzekIF--SYw4ckwGJXCHGVX6LJAEZkTj6HOs3gGH8OsvcZ4PLSJp-x68spXU3S0xKlEvN5U5ECJx4EdyV7mQUOOhtxfyXfI5wHbL0x3KvizNUMGkFwYgsUvWLMZg7WVvvCuyH_XMlA3LLK4Rvmel0ZRR4CSJ_D1sOCblhrx6Ku3wHmKoeiE
Content-Length: 114
Content-Type: application/json

{
    "@type": "http://ns.minddistrict.com/diary/schema/entry#emotion:6",
    "dt": "2014-04-12T11:41:09.817177"
}

The response will have a 400 status code and a description of the validation error(s):

HTTP/1.0 400 Bad Request
Content-Length: 287
Content-Type: application/json;charset=UTF-8

{
    "code": 400,
    "extra": [
        {
            "message": "Required input is missing.",
            "name": "emotion"
        },
        {
            "message": "Required input is missing.",
            "name": "intensity"
        }
    ],
    "message": "Invalid JSON input"
}

In the past, there were duplicate entries posted as a result of network issues. The API will ignore requests that try to post an entry for which the dt and fields are identical to an entry that already exists. The response to such a request contains the information about the already existing entry.

An entry is posted with identical dt and fields of an entry that already exists in the database:

POST /api/2/c/cb7bae66c0104b15ac661931811fe365/diary/entries HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABfxfsnijSVf9Tfcer0JhzekIF--SYw4ckwGJXCHGVX6LJAEZkTj6HOs3gGH8OsvcZ4PLSJp-x68spXU3S0xKlEvN5U5ECJx4EdyV7mQUOOhtxfyXfI5wHbL0x3KvizNUMGkFwYgsUvWLMZg7WVvvCuyH_XMlA3LLK4Rvmel0ZRR4CSJ_D1sOCblhrx6Ku3wHmKoeiE
Content-Length: 191
Content-Type: application/json

{
    "@type": "http://ns.minddistrict.com/diary/schema/entry#emotion:6",
    "dt": "2014-04-11T11:41:09.817177",
    "emotion": "happy",
    "intensity": 5,
    "situation": "I am awesome"
}

The response will return the already existing entry without creating a new entry:

HTTP/1.0 200 Ok
Cache-Control: max-age=0, no-cache, no-store, must-revalidate
Content-Length: 437
Content-Type: application/json;charset=UTF-8
Location: https://customer.minddistrict.com/api/2/c/cb7bae66c0104b15ac661931811fe365/diary/entries/e.2

{
    "@changes": {
        "creation_time": "2020-12-01T08:13:32",
        "modification_time": "2020-12-01T08:13:32"
    },
    "@type": "http://ns.minddistrict.com/diary/schema/entry#emotion:6",
    "@url": "https://customer.minddistrict.com/api/2/c/cb7bae66c0104b15ac661931811fe365/diary/entries/e.2",
    "dt": "2014-04-11T11:41:09",
    "emotion": "happy",
    "intensity": 5,
    "picture": null,
    "situation": "I am awesome"
}

View an entry

To view a single entry from a diary, send a GET request to the URL of that entry:

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

The response will be the entry:

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

{
    "@changes": {
        "creation_time": "2020-12-01T08:13:29",
        "modification_time": "2020-12-01T08:13:29"
    },
    "@links": [],
    "@type": "http://ns.minddistrict.com/diary/schema/entry#moment:1",
    "@url": "https://customer.minddistrict.com/api/2/c/cb7bae66c0104b15ac661931811fe365/diary/entries/e.1",
    "dt": "2020-12-01T08:13:29",
    "picture": null,
    "text": "I am flying!"
}

For more information about which attributes to expect in the response, please refer to the schema of the entry you are viewing.

Editing an entry

To modify an existing entry, send a PATCH request to the URL of the entry:

PATCH /api/2/c/cb7bae66c0104b15ac661931811fe365/diary/entries/e.1 HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABfxfsnijSVf9Tfcer0JhzekIF--SYw4ckwGJXCHGVX6LJAEZkTj6HOs3gGH8OsvcZ4PLSJp-x68spXU3S0xKlEvN5U5ECJx4EdyV7mQUOOhtxfyXfI5wHbL0x3KvizNUMGkFwYgsUvWLMZg7WVvvCuyH_XMlA3LLK4Rvmel0ZRR4CSJ_D1sOCblhrx6Ku3wHmKoeiE
Content-Length: 33
Content-Type: application/json

{
    "text": "Writing a novel"
}

To know which attributes you can edit on the entry, please refer to the schema of the entry you want to edit.

View diary metadata

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

Example request:

GET /api/2/c/cb7bae66c0104b15ac661931811fe365/diary 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: 857
Content-Type: application/json;charset=UTF-8

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

If the user does not have access to a diary, this request will fail with a 404 Not Found HTTP status code.