Skip to content

API documentation

Jump to bottom
Ben Silverman edited this page Jul 1, 2021 · 8 revisions

Table of contents

Introduction

This page documents REST API routes used internally by DPdash via Express. They are not for public consumption, rather they are used by various functions within the application.

This documentation is for a few API routes only. Other developers may feel free to document the rest of the API here as well.

Parameter types

Parameters are listed below for each API route. This is a brief explanation of the types of parameters you will encounter in this document.

  1. Express route params are URL parameters that are indicated by a colon (:) operator in Express routes. They go in the place of the colon-prepended keyword. Example: /api/v1/users/:uid/config/file will be transformed into /api/v1/users/my-username/config/file for my-username user ID.

  2. URL params: These are the simplest kind of parameters and are just appended to the URL with ? first, and then & for subsequent params. Example: /api/v1/studies/STUDY_ID/enrollment?start=2021-05-20&end=2021-07-20.

  3. POST body: these go in the body of the POST request. Since we use application/json as the request Content-Type, the body is always passed as JSON, compatible with the JavaScript Fetch API as documented here. Parameter names listed as "POST body" should be keys in the JSON body.

An asynchronous JS example of a POST request fetching enrollment data for a certain variable and assessment:

const data = {
  varName: 'some_variable',
  assessment: 'assessment_containing_variable'
};
const res = await fetch('/api/v1/studies/STUDY_ID/enrollment', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(data),
});
const { enrollmentsList } = await res.json(); // Now enrollmentsList should be an array

Configurations API

/api/v1/users/:uid/configs

GET

Get a list of configurations that this user can access (i.e. this user is in the readers array for each config).

Parameter Type Description Required
:uid URL (Express route param) The ID of the requesting user Yes

POST

Add, update, delete, share, or disable§ a configuration.

Parameter Type Description Required
:uid URL (Express route param) The ID of the requesting user Yes
add POST body The configuration object to add No*
edit POST body An object of keys/values to update in the configuration object† No*
remove POST body The MongoDB ObjectId of the configuration to delete No*
share POST body The MongoDB ObjectId of the configuration to share No*
shared‡ POST body An array of user IDs to whom the configuration is shared No‡
disable§ POST body The MongoDB ObjectId of the configuration to disable§ No*

*At least one of these is required for any action to occur.
†This object must include the keys _id, readers, config, name, and type.
‡This is required if share is also in the POST body.
§"Disable" in this context means to remove the user specified by :uid from the readers array, in other words, to unshare the configuration from that user.

Response:

  • add action: HTTP 201 with body
{
  uri: String    // The URI of the added configuration
}
  • All other actions: HTTP 201 with body
{
  message: 'success'
}

/api/v1/users/:uid/configs/:config_id

GET

Get a configuration from the database.

Parameter Type Description Required
:uid URL (Express route param) The ID of the requesting user Yes
:config_id URL (Express route param) The MongoDB ObjectId of the configuration to query Yes

Response:

{
  _id: String,               // MongoDB ObjectId of configuration
  owner: String,             // User ID of configuration owner
  name: String,              // Name of configuration
  type: String,              // Type of configuration
  readers: Array<String>,    // Array of user IDs for sharing
  config: Object,            // Object whose first key's value is an array of objects*
  created: Date,             // Date configuration was created
}

*This array of objects will match the schema specified here.

/api/v1/users/:uid/config/file

POST

Create a configuration from JSON following this schema. The below name and config params correspond to those same keys in the schema.

Parameter Type Description Required
:uid URL (Express route param) The ID of the user uploading the config file Yes
name POST body The name of the configuration No
config POST body An array of configuration objects Yes

Response: No response body, just HTTP 200 if successful.

Reports API

/api/v1/studies/:study/enrollment

GET

Get total enrollment for a study.

Parameter Type Description Required
:study URL (Express route param) The ID of the study/site to query Yes
start=YYYY-MM-DD URL Start date for date filtering No
end=YYYY-MM-DD URL End date for date filtering No

Response:

{
  enrollment: Number    // Total enrollment for study, based on applied filter(s)
}

POST

Get enrollment breakdown based on a variable.

Parameter Type Description Required
:study URL (Express route param) The ID of the study/site to query Yes
varName POST Body Name of variable to query Yes
assessment POST Body Name of assessment containing variable Yes
start=YYYY-MM-DD URL Start date for date filtering No
end=YYYY-MM-DD URL End date for date filtering No

Response:

{
  enrollmentsList: [
    {
      study: String,      // Study ID from query params
      varName: String,    // Variable name from query params
      value: Any,         // Value for variable for a single subject
      date: Date,         // Consent date for subject
    },
  ...
  ]
}

/api/v1/reports

GET

Get all reports the requesting user has access to (i.e. either the user is the owner, or the report is shared to the user).

Response:

{
  reports: [
    {
      _id: String,               // MongoDB ObjectId for the report
      reportName: String,        // Report title
      user: String,              // User ID of the creator
      readers: Array<String>,    // Array of user IDs for sharing
      created: Date,             // Date the report was created
    },
    ...
  ]
}

POST

Add a new report.

Parameter Type Description Required
reportName POST body The name of the report to add Yes
charts POST body An array of JS objects representing charts No

Response: No response body, just HTTP 200 if successful.

/api/v1/reports/:id

GET

Get a report by ID.

Parameter Type Description Required
:id URL (Express route param) The ID of the report to query Yes

Response:

{
  report: {
    _id: String,               // MongoDB ObjectId for the report
    reportName: String,        // Report title
    user: String,              // User ID of the creator
    readers: Array<String>,    // Array of user IDs for sharing
    created: Date,             // Date the report was created
    charts: [                  // An array of chart objects, which may be empty or contain empty fields
      {
        title: String,                   // The title of the chart
        chartType: String,               // The type of the chart (e.g. "bar")
        variableSingle: String,          // A single variable name (for multi-site charts)
        variableMulti: Array<String>,    // An array of variable names (for single-site charts)
        assessmentSingle: String,        // The name of the assessment containing the above variable(s)
        valueLabels: [                   // An array of value/label mappings
          {
	    value: String,               // A single value/range, or a list of comma-separated values/ranges
	    label: String,               // The label for the value(s)
	  },
          ...
        ]
      },
      ...
    ]
  }
}

PATCH

Update a report by ID.

Parameter Type Description Required
:id URL (Express route param) The ID of the report to update Yes
charts POST body An array of JS objects representing charts No
readers POST body An array of strings (user IDs for sharing) No

Response: No response body, just HTTP 200 if successful.

DELETE

Delete a report by ID.

Parameter Type Description Required
:id URL (Express route param) The ID of the report to update Yes

Response: No response body, just HTTP 200 if successful.

Clone this wiki locally