The REST API

The Bridge service API can be accessed at https://webservices.sagebridge.org.

Authentication

Bridge’s is a tenanted service in which each app has a separate set of accounts (shared between all studies in that app for study participants). Thus authentication sessions are always scoped to a specific app, which must be specified when sign in credentials are sent to the Bridge server. Once authenticated, the sign in call returns a JSON UserSessionInfo payload that includes a sessionToken property. That session token should be sent with all further requests to the Bridge server using the Bridge-Session HTTP header.

If you have not signed in, all services will return a 401 (unauthorized) error response.

If you are calling an endpoint for which you do not have sufficient permissions to make the call, the service will return a 403 (forbidden) error response.

Consent

If your study requires consent to participant, the first time a would-be participant user signs in to Bridge they will receive a 412 (Precondition Not Met) response along with the user's session. Participant-facing services will continue to return a 412 response and will not work until the user has called Bridge's services to consent to research. Note that a user can have a session but not be consented to participate in the study.

The user's current consent status is summarized in the UserSessionInfo object under the consentStatuses property where a ConsentStatus object exists for every consent that applies to the user in the study.

Data formats and submissions

Timestamps are expressed in ISO 8601 format (e.g. 2011-12-03T22:11:34.554Z), using the extended notation, to represent dates, dates and times, or times.

JSON objects returned from the Bridge server will contain a type property with a unique type string for that kind of object. This may aid deserialization. However, these type properties do not need to be submitted back to the server (the Bridge server can deduce the JSON object's type from the API endpoint). The Model Browser shows the type of every object returned by the Bridge server. Including the type property in your JSON back to the server is harmless.

JSON entities should be returned in their entirety to the Bridge server along with any changes that are desired in the object. Bridge does not support partial updates of JSON records, with the except of one legacy API where this is documented.

Roles

Many endpoints will return a 403 HTTP response (Forbidden) unless the caller is in the appropriate administrative roles.

Administrators (developers and researchers) can access most of the study management APIs available through Bridge.

Application versioning

If the version of the app making a request has a lower app version than the version configured by your app, services will return 410 (Service Gone) to indicate the application is obsolete and must be updated. This minimum required application version can be set separately for Android and iOS applications.

Deprecation and service warnings

Service endpoints are versioned independently, e.g. there may be one up-to-date service available at /v1/*, while another up-to-date service is available at /v2/*. If an API is versioned at a new version, all HTTP verbs that exist for that endpoint will work against that version of the endpoint. Separate "sub-path" endpoints are considered to be separate endpoints. For example /v1/api/consent and /v1/api/consent/email are considered separate endpoints and versioned separately.

When an endpoint has been deprecated, it will be marked as deprecated in our Swagger documentation, and the responses from that endpoint will include a Bridge-Api-Status header with an error message describing the issues with that call. The call will succeed, but at a future time, that endpoint may return 410, (Gone), and will no longer be functional. Please look for an alternative service in the API, and contact us if necessary to find a suitable service to which to migrate.

Server Responses and Errors

If a response returns no JSON payload, it will normally return a message, and this includes error responses:

{"message":"Not signed in."}

These messages are not localized. They are somewhat suitable for display to users, but mostly present as an aid to API developers.

Invalid entities return more complex errors with an "errors" property that breaks down the issues by field (the field key can be a nested set of properties into the JSON object structure). For example, here is the response to an invalid survey:

{   
   "message":"Survey is invalid: element[1].identifier is required",
   "errors":{   
      "element[1].identifier":[   
         "element[1].identifier is required"
      ]
   }
}

The second element of the survey (array syntax is zero-indexed) is missing an identifier property (which is required).

Swagger guidance

Bridge uses version 2.0 of the Open API Specification, which we have found ambiguous in a couple of areas. Here is how we use certain properties of the Swagger definition:

required: The caller is required to supply a property value when the model is submitted to the server. On an update, callers should return the value to the server even if it is unchanged (if not, it may be interpreted as a deletion of the property value).

readOnly: This value never needs to be provided by the caller or submitted back to the server (however, including it as part of the object is harmless, it will be ignored). System timestamps fall into this category.

x-nullable: When present, this is always set to false. This model property will never be null or missing when the model is returned from the server. This is a stronger promise than required. For example, most collection properties in Bridge will be set to empty objects or arrays in the JSON if no property is set, rather than being set to null or being excluded from the model JSON.