Changes API

Minddistrict provides the Changes API for external parties that wish to integrate the Minddistrict platform into their own systems. It provides a list of recent changes to objects within the platform, so that external systems can be kept in synch. An API consumer can periodically request this list and update the information kept in their own system to match.

This API is not intended to give a complete history of all events in the timeframe requested, but rather to answer the question “What objects have changes (since I last checked)?” In particular, if multiple events within the timeframe would produce change entries with the same content, the changes API may collapse these into a single change entry (meaning “This thing has changed”), rather than redundantly repeating them (“This thing has changed twice”). For example, if you request the tasks changes you will never see a particular user more than once in a single response: if that user has had multiple tasks created or completed within the timeframe requested, this is represented as a single change entry (“User XYZ’s tasks have changed”) rather than as one for each new task (“User XYZ’s tasks have changed twice”).

Warning

The changes API will only report changes occurring in the last 24 hours. If your aim is to keep your system in synch with the Minddistrict platform, make sure you request the last changes more often than this. If this is impossible (for instance if your system suffers an outage lasting more than 24 hours) you should perform a global synchronisation, after which you can continue to use the changes API as before. For example, if you are tracking changes to user tasks with the changes API, you would perform a global synchronisation by updating the tasks for all users: after this the ongoing changes can again be picked up via the changes API.

The Changes API currently contains information about client’s and professional’s tasks. While tasks are the only changes currently reported, we already require consumers to specify the type of changes they want, so that new change types can be added to the API in a backwards-compatible manner.

Authentication and rate limiting

The changes API reports global information, potentially related to all clients and professionals in the platform. For this reason, it is only accessible to user accounts that have been granted a specific permission. Ordinary user accounts do not have this permission: you will have to contact Minddistrict to arrange a “system access user” if you wish to make use of this API.

We anticipate most integrations making no more than a handful of requests per minute; the Minddistrict API as a whole is rate limited to 20 requests per second.

Discovering the changes URL

The changes URL is discoverable in the @links metadata of the application under the name changes.

The following query:

GET /api/2 HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABfxfsqMvSZEjjS_KUVrDT1vFD-8Uer2suLv7WudYevQ4-b4KFk9JlinFKGLmcNkvhjrt_woaLqBbjdiO1Mx5Cn-M96GXMqsafOPNYWNTgy5K2uexHc5DRHNRPntGnDVQNB5B7NzyOTpWY9wJkH6vdBHYqGnx0tQHVQYjODwixfvhuQw3vz0jBbHvR2-TDc5ZqCrasC

The response will contain the URL to the Changes API:

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

{
    "@changes": {
        "creation_time": "2020-12-01T08:13:27",
        "modification_time": "2020-12-01T08:13:27"
    },
    "@links": [
        {
            "name": "authenticate",
            "url": "https://customer.minddistrict.com/api/2/authenticate"
        },
        {
            "name": "changes",
            "url": "https://customer.minddistrict.com/api/2/changes"
        },
        {
            "name": "configuration.labels",
            "url": "https://customer.minddistrict.com/api/2/configuration/labels"
        },
        {
            "name": "configuration.labels.items",
            "url": "https://customer.minddistrict.com/api/2/configuration/labels/items"
        }
    ],
    "@type": "http://ns.minddistrict.com/application",
    "@url": "https://customer.minddistrict.com/api/2",
    "mode": null,
    "name": "Customer application",
    "warning": null,
    "web_url": "https://customer.minddistrict.com"
}

Request

After discovering the URL to the Changes API, send a GET request to this URL. The request must contain two query parameters: type specifies the type of change objects you are interested in (at present only the value tasks is accepted), and since gives the period to report changes over. The value of since should be an ISO-8601 formatted UTC date time. It should be no more than 24 hours in the past; if it is earlier you will receive no error, but you will not receive notification of any changes from more than 24 hours in the past.

The objects in the response depend on the type request parameter, and are described below.

Here we show a changes request.:

GET /api/2/changes?since=2015-03-16T09:00:00&type=tasks HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABfxfsqMvSZEjjS_KUVrDT1vFD-8Uer2suLv7WudYevQ4-b4KFk9JlinFKGLmcNkvhjrt_woaLqBbjdiO1Mx5Cn-M96GXMqsafOPNYWNTgy5K2uexHc5DRHNRPntGnDVQNB5B7NzyOTpWY9wJkH6vdBHYqGnx0tQHVQYjODwixfvhuQw3vz0jBbHvR2-TDc5ZqCrasC

The response will be the list of change objects. Note however that batching parameters are not supported, because of the instability of the collection: changes to task state can radically change the contents and ordering of the collection, which would make iterating over it in batches unsafe.:

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

{
    "@items": [
        {
            "@type": "http://ns.minddistrict.com/change/tasks",
            "url": "https://customer.minddistrict.com/api/2/c/cb7bae66c0104b15ac661931811fe365/tasks/items",
            "user": {
                "@type": "http://ns.minddistrict.com/user-reference/client",
                "id": null,
                "url": "https://customer.minddistrict.com/api/2/c/cb7bae66c0104b15ac661931811fe365"
            }
        },
        {
            "@type": "http://ns.minddistrict.com/change/tasks",
            "url": "https://customer.minddistrict.com/api/2/p/35fb5c76bdf446f79aef960da609a39b/tasks/items",
            "user": {
                "@type": "http://ns.minddistrict.com/user-reference/professional",
                "id": null,
                "url": "https://customer.minddistrict.com/api/2/p/35fb5c76bdf446f79aef960da609a39b"
            }
        }
    ],
    "@links": []
}

The since parameter allows you to limit the changes reported to those that have taken place after your most recent request. However this is intended only to help avoid excessive reprocessing of changes, and is not a reliable synchronisation mechanism: because of the time spent in network traffic and processing, you cannot choose a since parameter that will guarantee both that you never see the same change notification twice and that you never miss a change notification. API consumers should err on the side of caution, by setting since to some small amount earlier than their most recent request (e.g. 1 minute if they make a new request every 5 minutes); their code should deal gracefully with the possibility that the same change notification is returned across multiple requests.

Change objects

A change object is a JSON object with at least a key "@type". The value of this key will be the value you gave in the type= query parameter, under the namespace http://ns.minddistrict.com/change; for instance the type=tasks query parameter gets you change objects with @type http://ns.minddistrict.com/change/tasks.

Future additions to the API may include multiple types in the output of a single request, so you are encouraged to check the "@type" value when processing changes API responses.

type=tasks

A tasks change object (http://ns.minddistrict.com/change/tasks) indicates that the active tasks for a particular user have changed. (This might mean a task was created, or was completed or deleted.) The creation (or completion) of a single task can trigger multiple change objects, if that task is relevant for multiple users (e.g. if it is to be handled by any member of the Secretaries group).

The object contains the following keys:

Structure of a change object of type tasks

Key

Value

@type

"http://ns.minddistrict.com/change/tasks"

url

API URL to the client’s tasks.items view. API consumers can use this URL to retrieve the new list of active tasks for that user.

user

A user reference to the user whose tasks were updated. This includes only basic identifying information; more details can be retrieved via the client API if desired.