Backend API Requests Documentation

Overview

The backend APIs are a series of available REST API endpoints that developer may interface with for data queries. The knowledge about these endpoints are not required by average users, since all the request and communications are hidden from users. However, these will likely come in handy for people who want to modify the backend or develope their own frontend pipelines.

There are many modules among the backend APIs, which can be divided based on functionalities.

  1. Authentication Module for User (Research/Admin/Mobile) related actions.

  2. Queries Module for requesting data from database.

  3. SQL Database Update Module for changing patient/device information in database.

  4. Upload Module for handling file uploads from user.

  5. Survey Module for handling online-survey related changes. This is non-neurostimulator specific module.

Authentication Module

The Authentication Module file contain all routes that handles account creation and authentication. Most functions are wrapper around the Django REST Knox library that performs Authentication Token management.

class APIs.Auth.UserRegister(**kwargs)

User Registration (Web Account Only).

POST: /api/registration

Parameters

  • Email (string) – Email address will also serve as unique username. Must be a properly formated Email address and unique within database.

  • UserName (string) – Human readable name of the user.

  • Institute (string) – Common institute name of the user. This allow sharing of data among multiple users within same institute.

  • Password (string) – Password of the account. Database will hash the password for security. User may also choose to perform end-to-end encryption during transmission if they desire.

Returns

Response Code 200 if success or 400 if error. Response Body contains authentication token and user object.

class APIs.Auth.UserAuth(**kwargs)

User Authentication (Web Account Only).

POST: /api/authenticate

Parameters

  • Email (string) – Email address also serves as unique username.

  • Password (string) – Password of the account. Database will hash the password for security. User may also choose to perform end-to-end encryption during transmission if they desire.

  • Persistent (Boolean) – If the token’s expiration date should be extremely long or not.

Returns

Response Code 200 if success or 400 if error. Response Body contains authentication token and user object.

class APIs.Auth.UserTokenRefresh(**kwargs)
class APIs.Auth.FetchAuthorizedInstitute(**kwargs)

NOT IMPLEMENTED

class APIs.Auth.UserSignout(**kwargs)

User logout while detroying the authentication token.

POST: /api/logout

Parameters

refresh (string) – the refresh-token for persistent connection.

Returns

Response Code 204.

class APIs.Auth.Handshake(**kwargs)

Confirming that the BRAVO server exist.

POST: /api/handshake

Returns

Response Code 200.

Queries Module

The Queries Module file contain all routes called by React Frontend to request data for display. These functions are mostly top-level wrappers that call low-level computation and processing scripts outlined in other documentation.

All Queries require UserAuthentication in request, indicating that if a request is made without Authentication Token will be automatically rejected. Therefore, NotAuthenticated error will not be discussed in each function but implied.

All Queries will be subjected to a simple “Access Verification” function that determine what data the user has access to. Currently only 3 tier of access control is added:

  1. Tier 0 = Not Accessible

  2. Tier 1 = Owner Access (You uploaded the data or that you are Admin/Clinician account)

  3. Tier 2 = Permissible Access (You didn’t upload the data but an Admin has granted you access through Admin Panel).

class APIs.Queries.QueryDatabaseInfo(**kwargs)

Query current database information.

POST: /api/queryDatabaseInfo

Returns

Response Code 200. Response Body contains number of unique patients in database and size of data the user has access to.

class APIs.Queries.QueryPatientList(**kwargs)

Query list of accessible patients in database.

POST: /api/queryPatients

Returns

Response Code 200. Response Body contains list of patient object.

class APIs.Queries.QueryPatientAccessTable(**kwargs)

Query list of accessible patients in database.

POST: /api/queryPatientAccessTable

Returns

Response Code 200. Response Body contains list of patient object with access information.

class APIs.Queries.QueryPatientInfo(**kwargs)

Query detailed patient information.

POST: /api/queryPatientInfo

Parameters

id (uuid) – Patient Unique Identifier as provided from QueryPatientList route.

Returns

Response Code 200. Response Body contains a single patient object with detailed information.

class APIs.Queries.QueryProcessingQueue(**kwargs)

Query current processing queue list

POST: /api/queryProcessingQueue

Returns

Response Code 200. Response Body contains list of processing queue items owned by the request owner.

class APIs.Queries.QueryTherapyHistory(**kwargs)

Query all therapy histories from desired patient.

The therapy histories include both therapy change logs and clinician configurations.

The therapy histories do not include how patient adjust their stimulation amplitude within range because this information is not saved. If recording is enabled, user may query the stimulation amplitude changes.

POST: /api/queryTherapyHistory

Parameters

id (uuid) – Patient Unique Identifier as provided from QueryPatientList route.

Returns

Response Code 200 if success or 400 if error. Response Body contains list of all Therapy Change Logs and Therapy Configurations.

class APIs.Queries.QueryAverageNeuralActivity(**kwargs)

Query all Average Neural Activity data.

The Average Neural Activity query will return processed power spectral density calculated from time-domain data. This is not the same as the on-board FFT result shown on Tablet.

Raw time-domain data will not be returned from this route.

POST: /api/queryAverageNeuralActivity

Parameters

id (uuid) – Patient Unique Identifier as provided from QueryPatientList route.

Returns

Response Code 200 if success or 400 if error. Response Body contains list of all Average Neural Activity.

class APIs.Queries.QueryNeuralActivityStreaming(**kwargs)

Query Neural Activity Streaming Data.

The Neural Activity Streaming query allows for multiple type of requests, based on what is sent in request body.

POST: /api/queryNeuralActivityStreaming

Request List of Available Neural Activity Streaming Data

{
  "requestOverview": true,
  "id": "(uuid)",
}

Request specific Neural Activity Streaming Recording based on recording ID

requestFrequency is optional if user want to request power value from different frequency instead of the automated algorithm

{
  "requestData": true,
  "id": "(uuid)",
  "recordingId": "(uuid)",
  "[requestFrequency]": "(int)"
}

Request update on power spectrum data for rendering

channel is the convention of channel identification, which is usually CONTACT_CONTACT_HEMISPHERE (i.e.: ZERO_TWO_LEFT)

This is a faster operation than request Neural Activity Streaming Recording using requestFrequency because this operation does not transmit raw data.

{
  "updateStimulationPSD": true,
  "id": "(uuid)",
  "recordingId": "(uuid)",
  "channel": "(string)",
  "centerFrequency": "(int)",
  "stimulationReference": "(string)",
}

Update Neural Activity Streaming result with or without cardiac filter

Permission denied unless you are the data owner (Permission == 1)

{
  "updateCardiacFilter": "(boolean)",
  "id": "(uuid)",
  "recordingId": "(uuid)"
}
Returns

Response Code 200 if success or 400 if error. Response Body contains requested data, often large due to time-domain data transmission.

class APIs.Queries.QueryMultiChannelStreaming(**kwargs)

Query all Multi-Channel Streaming Data.

The Indefinite Streaming query allows for multiple type of requests, based on what is sent in request body.

POST: /api/queryMultiChannelStreaming

Request List of Available Indefinite Streaming Data

{
  "requestOverview": true,
  "id": "(uuid)",
}

Request specific Indefinite Streaming Recording based on list of provided devices and timestamps

{
  "requestData": true,
  "id": "(uuid)",
  "timestamps": ["(int)"],
  "devices": ["(uuid)"]
}
Returns

Response Code 200 if success or 400 if error. Response Body contains requested data, often large due to time-domain data transmission.

class APIs.Queries.QueryChronicNeuralActivity(**kwargs)

Query all Chronic Neural Activity Data.

The Chronic Neural Activity data includes single power-band recorded using sensing-enabled settings, patient-reported events and event power spectrums.

POST: /api/queryChronicNeuralActivity

Parameters

  • id (uuid) – Patient Unique Identifier as provided from QueryPatientList route.

  • requestData (boolean) – Always true to request data.

  • timezoneOffset (int) – seconds offset compare to Universal Time Coordinate. You can request this value from your browser through new Date().getTimezoneOffset()*60.

Returns

Response Code 200 if success or 400 if error. Response Body contains Chronic Neural Activity and Event PSDs.

class APIs.Queries.QueryAdaptiveStimulation(**kwargs)
class APIs.Queries.QuerySessionOverview(**kwargs)

Query all JSON sessions related to a patient.

This route will provide user with all JSON files uploaded related to a specific patient ID. This is useful to identify raw unprocessed file for analysis outside of the web platform.

User may also request deletion of session file (and all associated data) by requesting deletion.

POST: /api/querySessionOverview

Parameters

id (uuid) – Patient Unique Identifier as provided from QueryPatientList route.

Returns

Response Code 200 if success or 400 if error. Response Body contains nothing if deleteSession is requested, otherwise contain list of available session files.

class APIs.Queries.QueryExternalRecordings(**kwargs)

Query all External Recordings related to a patient.

class APIs.Queries.QueryPredictionModel(**kwargs)
class APIs.Queries.QueryMultipleSegmentComparison(**kwargs)
class APIs.Queries.QueryPatientEvents(**kwargs)
class APIs.Queries.QueryCustomAnnotations(**kwargs)
class APIs.Queries.QueryCustomizedAnalysis(**kwargs)

Query Customized Analysis.

class APIs.Queries.QueryMobileRecordings(**kwargs)

Query Customized Analysis.

class APIs.Queries.QueryRecordingsForAnalysis(**kwargs)

Query Recording Raw Data for Analysis.

class APIs.Queries.QueryImageModelDirectory(**kwargs)

Query all Image models store in the patient’s imaging folder.

This route will provide user with all model descriptor related to a specific patient, assuming there are imaging models in the patient’s imaging folder.

POST: /api/queryImageDirectory

Parameters

id (uuid) – Patient Unique Identifier as provided from QueryPatientList route.

Returns

Response Code 200 if success or 400 if error. Response Body contains descriptor, a dictionary that describe initial rendered objects and their parameters, and availableModels, an array of dictionary with field {file, type, mode}.

class APIs.Queries.QueryImageModel(**kwargs)

Query all Image models store in the patient’s imaging folder.

This route will provide user with all model descriptor related to a specific patient, assuming there are imaging models in the patient’s imaging folder.

POST: /api/queryImageModel

Parameters

  • Directory (uuid) – Patient Unique Identifier as provided from QueryPatientList route.

  • FileMode (string) – “single” or “multiple”, define whether the API should return individual file or pagination for multiple requests.

  • FileType (string) – “stl”, “tracts”, or “electrode”, define what kind of model the server should retrieve. This defines the decoder function.

  • FileName (string) – filename of the model.

Returns

Response Code 200 if success or 400 if error. Response Body contains an octet-stream (binary buffer) for “stl” and “electrode”, or array of points for tracts.

class APIs.Queries.QueryCircadianPower(**kwargs)

SQL Database Update Module

Warning

Hidden - Under Revision

Upload Module

Warning

Hidden - Under Revision

Survey Module

Warning

Hidden - Under Revision