DDM offers several interfaces to retrieve different parts of the data collected for a
given project. For example, it is possible to retrieve only the data donations,
only the questionnaire responses, or the complete data including data donations,
questionnaire responses and metadata.

This can be useful to, for example:

* access specific parts of the data collected for a project directly from within your R-
or Python-analysis scripts.
* provide your participants with a personalized dashboard or report containing
personalized insights based on the data they just donated to a project. This can
serve as a great incentive for participation.
* build custom dashboards to track the progress of your data collection in more detail.


For this, DDM implements RESTful APIs. Currently, only GET requests are allowed
through these endpoints.


=== Authentication Schemes

The APIs listed here can be accessed using Token authentication. A Token
is always associated to a specific project and must be created through the
web application (on the main project site, go to the _Project Hub_ and in the
_Data Center_ click on _Manage Access Token_).

Token expiration can be set to a maximum of 90 days after which they must be renewed.


=== Data API

Description:: Download all data collected for a given donation project.

URL:: /api/project/<project ID>/data

Allowed Methods:: `GET`

Implemented Query Parameters:: None

Response:: Returns a ZIP-Folder containing a json file with the following structure:
[source, json]
----
{
    "project": {
        "pk": 1,
        "name": "project name",
        "date_created": "2022-12-19T08:49:18.363880+01:00"
    },
    "donations": {
        "blueprint name 1": [
            {
                "participant": 1
                "project": 1,
                "time_submitted": "2022-12-19T08:49:18.363880+01:00",
                "consent": true,
                "status": "success",  # One of "success" (donation successful); "pending" (donation not attempted); "failed" (donation failed due to an error); "nothing extracted" (all data filtered out)
                "data": [
                    {
                        "extracted_field_1":  "value1_entry1",
                        "extracted_field_2":  "value2_entry1",
                        # ...
                    },
                    {
                        "extracted_field_1":  "value1_entry2",
                        "extracted_field_2":  "value2_entry2",
                        # ...
                    },
                    # etc.
                ]
            }
        ],
        "blueprint name 2": [
            {
                "participant": 1,
                "project": 1,
                "time_submitted": "...",
                # etc.
            }
        ]
    },
    "questionnaire": [
        {
            "participant":  1,
            "project":  1,
            "time_submitted":  "2023-01-19T08:49:18.363880+01:00",
            "responses": {
                "variable_name": "answer to question",
                "variable_name-item-value": "answer to item"
            },
            "meta_data":  {  # For data validation purposes: contains one entry per question consisting of meta information about how the question was presented to the participant:
                "question-id": {
                    "response": "1",  # Can be a dict of form {"item-id":  "item-response", ...} for question types with item responses
                    "question": "question text in html format as displayed to participant",
                    "items": [
                        {
                            "id": "33",
                            "label": "label text in html format as displayed to participant",
                            "label_alt": "alternative label text in html format as displayed to participant",  # only applies to semantic differential
                            "index": "1",
                            "value": "1",
                            "randomize": false
                        }
                    ]
                }
            }
        }
    ],
    "participants": [
        {
            "pk":  1,
            "project":  1,
            "external_id":  "DMXdpfVyksagfqql2cTgp8kF",
            "start_time":  "2023-01-18T08:49:18.363880+01:00",
            "end_time":  "2023-01-20T08:49:18.363880+01:00",
            "completed":  true,
            "extra_data":  {
                "url_param": {
                    "some_url_parameter": "some value extracted from this parameter when the briefing page was called.",
                    # ...
                }
            }
        }
    ]
}
----

Example::
[source]
----
GET /api/project/4/data HTTPS
Authorization: Token 1176fcf7d0203db1e097861ef7442b328f1bb7f1
Host: <hostname>

zip-file
----

=== Donations API

Description:: Download all data collected for a given donation project.

URL:: /api/project/<project ID>/donations

Allowed Methods:: `GET`

Implemented Query Parameters:: `participants`, `blueprints`; both can be supplied
as a comma-separated list of _external participant IDs_ or _blueprint IDs_. If not
specified, donations for all participants/blueprints associated with a project will be
returned.

Response:: Returns a json object containing all donated data matching the query parameters.

Example::
[source]
----
GET /api/project/4/donations HTTPS
Authorization: Token 1176fcf7d0203db1e097861ef7442b328f1bb7f1
Host: <hostname>

{
    'Blueprint 1': [
        [<donations participant 1>], [<donations participant 2>], [<donations participant 3>]
    ],
    'Blueprint Zwei': [
        [<donations participant 1>], [<donations participant 2>], [<donations participant 3>]
    ]
}


GET /api/project/4/donations?participants=1,2&blueprints=1 HTTPS
Authorization: Token 1176fcf7d0203db1e097861ef7442b328f1bb7f1
Host: <hostname>

{
    'Blueprint 1': [[<donations participant 1>], [<donations participant 2>]]
}
----


=== Responses API

Description:: Download all questionnaire responses collected for a given donation project.

URL:: /api/project/<project ID>/responses

Allowed Methods:: `GET`

Implemented Query Parameters:: `participants`; can be supplied
as a comma-separated list of _external participant IDs_. If not
specified, donations for all participants associated with a project will be
returned.

Response:: Returns a json object containing all questionnaire responses matching the query parameters.

Example::
[source]
----
GET /api/project/4/responses HTTPS
Authorization: Token 1176fcf7d0203db1e097861ef7442b328f1bb7f1
Host: <hostname>

[
    {'variable_a': 'response', 'variable_b': 'response'},
    {'variable_a': 'response', 'variable_b': 'response'},
    {'variable_a': 'response', 'variable_b': 'response'}
]


GET /api/project/4/responses?participants=1,2 HTTPS
Authorization: Token 1176fcf7d0203db1e097861ef7442b328f1bb7f1
Host: <hostname>

[
    {'variable_a': 'response', 'variable_b': 'response'},
    {'variable_a': 'response', 'variable_b': 'response'}
]
----
