API Basics

The MyDataHelps API is a REST-based interface, which means that applications make requests to the API by accessing specific URLs using HTTP. One of the hallmarks of REST is that the API calls are stateless, meaning each request is a single, self-contained operation.

Base URL

The endpoint for the MyDataHelps API is:

https://designer.mydatahelps.org/api

For example:

https://designer.mydatahelps.org/api/v1/administration/projects/:projectId/participants

In the API reference, the base URL is usually omitted for brevity, and only the bolded part given.

Project Identifiers

All API calls are specific to a single project. You will generally identify your project in the resource url (e.g., api/v1/administration/projects/:projectId/participants).

You can find your project identifier in your project settings under the “About Settings” tab.

Authentication

Every API call must contain an access token to authorize access to your project’s data. This will be sent in the HTTP header as a header key named “Authorization” containing the value “Bearer YOUR_TOKEN”. For more information on how to get an access token, see Authentication.

Required Headers

Every API call requires two fields in the HTTP request header:

Data Formats

Data sent to and received from the MyDataHelps API will be in JSON format.

REST Basics

This section gives a brief introduction to REST APIs in general.

Resources

The URLs are centered around resources, which identify the kind of data you’re working with. For example, the URL api/v1/administration/projects/:projectId/participants is the URL for any API call that deals with project participants: querying them, adding them, updating them, and so on.

HTTP Verbs

Every API call uses a specific HTTP verb, which tells the system what kind of action you want to take with the resource. The verbs are summarized in the table below, but not all verbs apply to every resource. Consult the documentation for each resource to see what verbs are supported.

Segments

Some segments of the API URLs begin with a : to indicate that they are variables conveying information about the specific resource you wish to access. For example, the URL api/v1/administration/projects/:projectId/participants/:participantID identifies a resource with both a project ID and a participant ID.

Parameters

In addition to the segments, many API calls use query parameters and/or request body data to send data to the server.

Query parameters are usually found on GET requests, specifying the details of the query. For example, in a request for participants, you can add query parameters to control how the results are broken up into pages: api/v1/administration/projects/:projectId/participants?pageSize=1&pageNumber=2.

Body data is usually used in PUT and POST requests to pass along the specific resource data you wish to add/update. For example, in a POST request to api/v1/administration/projects/:projectId/participants, the body of the request would specify the details of the participant(s) you wanted to add.

Error Handling

The response header for each request contains a status code indicating whether the request was successful. Common status codes you will encounter are: