Evolution of the Bridge System
The Bridge platform encompasses two principle domains: the mobile app domain, including support for the mobile app development lifecycle and support for a mobile app in production; and the scientific research domain, which includes the APIs to conduct research.
Since first releasing the Bridge platform in 2015, Sage engineers have worked with dozens of research teams on a variety of research studies that have used mobile phone apps to conduct some or all of their research. We have learned a great deal about the needs of scientific researchers in conducting these mobile studies. This has left us dissatisfied with the impedance between our APIs, and the concepts that are used by scientists to organize their research.
To address these shortcomings, the Bridge engineering team will be evolving our science APIs to improve our support for scientific research, with an emphasis on improving our support for recruiting and retaining participants, and ensuring they comply with study protocols during research. Additionally we hope to improve the metadata associated with the data generated by a study, in order to make it easier to analyze.
We do not expect this second revision of the science APIs to be compatible with the earlier APIs. When they are ready for production, new studies will want to use the second generation APIs for study design exclusively. Version 2 APIs are not currently complete or ready for production. Because these science APIs are mostly administrative in nature, we will phase out the v1 APIs once we have updated downstream consumers, such as the Bridge Java SDK.
This document describes these changes at a high level because the concepts and APIs will be introduced into our SDKs and documentation over the next couple of years. We hope to reduce confusion as the terminology changes to reflect our new system.
The Science Domain
The most significant change to the Bridge system will be a recognition that a single mobile app is often used in multiple scientific studies. The top-level “tenant” of the Bridge system will be an app context, rather than a study. Instead, an app will be able to contain multiple studies, being run by different organizations, using different or related schedules which can vary by study arm. (Observational studies may only have one study arm.)
Study designs will be associated with a richer enrollment model that codifies best practices for e-consent, and captures more information about users, earlier in the process, as part of our improved support for understanding recruitment challenges. The system will be able to allocate participants using standard mechanisms such as stratified random allocation, or researchers can use an external ID to enroll a user in a specific study and study arm.
Schedules define the performance of assessments that are grouped together into sessions and study bursts, triggered from study activity events that are meaningful waypoints in a person’s participant in the study.
Assessments will provide us with a more sophisticated and flexible set of objects to model surveys and other tasks. Our goal is to improve tooling support so that study designers can select and customize assessments that have been validated and documented by the research community.
This richer design will be associated to the data that is uploaded from a study, so researchers can analyze their data in simpler and more powerful ways. One step in that process will be the collection of baseline characteristics before a participant is allocated to a study arm, to simplify later data analysis. Study designers can define these characteristics based on their research or recruitment interests. We will also provide much more visibility into participant adherence so study coordinators can work with participants to ensure they successfully engage with the study.
Changes to the science APIs
While these APIs will continue to be available, we intend to replace them with new APIs to implement the domain as described above:
| Name | APIs | Comment |
|---|---|---|
| Scheduling and activities | /v4/schedules, /v3/scheduleplans, /v3/activities, /v4/activities, /v3/compoundactivitydefinitions |
All of these APIs will be replaced with an explicit study design and an explicit schedule of assessments based on a participant’s assignment to one or more arms of a study. |
| Surveys and Upload Schemas | /v3/surveys, /v3/uploadschemas, /v4/uploadschemas |
These will be replaced by assessments, and will include configuration specific to each assessment. This should pull some config out of the more generic app configs, into a model that can be better supported by tooling. |
| Consent | /v3/consents, /v3/subpopulations, /v3/itp |
Consent will continue to exist, but they will be directly associated with a study (each study will include details about enrollment and consent requirements). |
| Shared Modules | /v3/sharedmodules |
These were not adopted, and will be replaced with a shared assessment library. |
| Substudies | /v3/substudies |
Substudies will be replaced with Studies that are accessible through organizational membership. This will be separate from enrollment in a study as a participant. |
| External IDs | /v3/externalids, /v4/externalids |
External IDs will continue to be used, but they will associate users to specific studies in an app (not just an organization). |
The Mobile Development Domain
The mobile development domain is better understood by Sage engineers, and we anticipate less change in the APIs that support the mobile software development lifecycle. That includes the following APIs:
| Name | APIs | Comment |
|---|---|---|
| Authentication | /v3/auth*, /v4/auth/*, /v3/oauth |
No changes, although we continue to integrate administrative accounts (developers, researchers, study designers) more closely with Synapse for the convenience of users. |
| App Config | /v3/appconfigs* and /v3/appconfigs/elements/* |
No changes, though we believe a lot of this configuration will be associated directly with assessments in the future. |
| File Hosting | /v3/files/* |
No changes. |
| Push Notifications | /v3/notifications/* and /v3/topics/* |
No changes, although we will introduce more sophisticated functionality to retain participants and promote compliance with study protocols. |
| Reports | /v3/reports/*, /v4/reports/*, and /v3/participant/reports/* |
These will be augmented, but are not being removed or replaced. |
| Templates | /v3/templates/* |
No changes. |
| Uploads | /v3/uploads, /v3/uploadstatuses, /v3/recordexportstatuses, /v3/healthdata |
Mobile apps continue to need an upload system that will integrate with device services, however, these APIs will be augmented to carry over more information about the study design that led to the production of the data in the first place. |
| Users | /v3/users |
These APIs were created for profile support, and have been replaced by other APIs, but will continue to exist. |
| Activity Events | /v1/activityevents |
No changes (usage of this API is expected to decline). |
Administrative APIs
Administrative APIs may grow but with one exception, will not change:
| Name | APIs | Comment |
|---|---|---|
| Cache | /v3/cache/* |
|
| Participants | /v3/participants/* |
These will continue to be used to retrieve all accounts in the system, either study participants or administrative accounts, but with new filtering options, new APIs, etc. |
| Scheduler Configs | /v3/schedulerconfigs |
|
| Studies | /v3/studies/* |
|
| Worker APIs | /v3/studies/{studyId}/* |
These will be changed to the /v3/apps/{appId}/ namespace. The old APIs will continue to exist, but they will be removed from our SDKs and documentation. |