Visit The University of Sydney, Faculty Of Science Web-Site
Visit Physics of Circadian Rhythms and Sleep Web-Site

User Guide: Browser Interface

This document provides a brief introduction to requesting sleep predictions and recommendations, based on the Sydney-CRC Model of Sleep and Alertness, via the Web-Browser interface at https://www.alertnessapi.com.

If you have not already done so, you should start with the general user guide.

For a guide to submitting queries and retrieving results using the REST interface, see the REST interface guide.

Access Flow

Basic use involves uploading your json file using the web-form available at https://www.alertnessapi.com

If your uploaded file is valid then you will receive an email, a few seconds to a few minutes later, containing links that you can follow to download your result. The variability in response time depends on details of your query. Calculating a few days to a week worth of sleep and alertness predictions currently takes a few seconds to complete. Calculating a few days to a week worth of sleep recommendations currently takes between thirty seconds and a few minutes to complete. The current server can evaluate up to sixteen simultaneous queries.

Authentication

With the exception of the json-schema definition, all access requires two request parameters for authentication: userName and password.

Accessing endpoint will provide an authentication form for you to enter these details.

Alternatively you can add your credentials manually in the form of query parameters. That is, you can include the equivalent of:

?userName=<yourAPIusername>&password=<yourAPIpassword>

in addition to any other required request or path parameters.

Input

There is a formal definition of the structure of the input accepted by the API available in json-schema format. If you need this it can be viewed/downloaded by pointing your browser at:

https://www.alertnessapi.com/v3/schema/api-input

If you submit a file containing structurally valid input then a Successfully uploaded: message will appear at the top of the web-form.

If you upload a file that violates this basic structure then an Invalid Query: message will appear at the top of the web-form.

Currently it is not possible to view the schema violations in your web-browser. If you have trouble identifying a problem with your file then you will need to submit the files contents using the REST interface, where details of the violations are returned in response to a POST to the /query endpoint.

Valid Input

  1. Must be either a json object or json array, failure to meet this requirement will result in:
    • either an Invalid Query: Bad json file, expected array or object. or an Upload failed message after you click submit;
  2. Each json object must conform to the json-schema definition of the inputs, failure to meet this requirement will result in:
    • an Invalid Query: does not match expected format, specified by json-schema… message after you click submit;
  3. Further constraints exist for the inputs which are not captured by their json-schema definition, so are not identified at upload time, failure to meet these requirements will result in:
    • the result links you receive by email including an “error” file detailing the violations.

The most commonly violated additional requirements, those not identified until a query is evaluated, are:

  • Date-time constraints cannot overlap – that is, any specified forced-wake must have ended before another can begin, keeping in mind that any specified lead and lag time are prepended and appended, respectively, to the specified date-times (these lead and lag periods are part of the forced-wake); and
  • start_time must be earlier than the earliest specified date-time.

Other Input Considerations:

  • Date-time format must be YYYY-MM-DDTHH:mm:SS+HH:mm;
  • Forced-wake with a label containing “shift” (eg. shift, day-shift, etc) are treated differently to any forced-wake with a label that does not contain “shift” – sleep recommendations based on alertness optimise over the alertness values predicted during shift.

Duration of the Results

  • All results, whether predictions or recommendations, start from start_time;
  • The end of the duration covered by predictions or recommendations depends on several input fields:
    • If duration_days is not specified as an input then the end will be at the latest specified date-time;
    • If duration_days is specified to a value longer than the last specified date-time then that value is used for the duration covered by the returned results.

Endpoints

A primary web browser endpoints are:

  • /v3 – Currently, just redirects to /v3/jsonupload
  • /v3/jsonupload – web-form to upload a json formatted input file
  • /v3/results/{fileName.json} – Links you receive in result emails have this form.

Additionally there are several “under construction” endpoints to view queries and results from within the browser.

  • /v3/listQueries – a table of your recent queries.
  • /v3/listDownloads – a table of your recent download files
  • /v3/viewQuery/{queryId} – view an individual query
  • /v3/viewQueryGroup/{uploadId} – view all queries from an upload
  • /v3/viewResult/{queryId} – view an individual result

/jsonupload

The /jsonupload endpoint provides web-form for uploading a json formatted input file.

/listQueries

Display a table of your recent queries, with links to view the query or the result.

/listDownloads

Display a table of your recent download files, with links corresponding to those you should receive by email.

/viewQuery

The /viewQuery endpoint provides a way to view queries you have submitted in the browser.

Whenever you successfully upload a file the file is assigned an upload id and each query is assigned a query id.

If you know your query id then you can add it as a path variable to the /viewQuery endpoint to view the query in your browser. That is, assuming that you uploaded a file containing a query which was assigned id 42 you can direct your browser to:

https://www.alertnessapi.com/v3/viewQuery/42

to view it. Start from the /listQueries end point if you do not know the relevant query id.

If you uploaded a file containing an array of queries, and that file was assigned upload id 13, then you can direct your browser to:

https://www.alertnessapi.com/v3/viewQueryGroup/13

to view all the queries it contained.

/viewResult

The results of a query, once they are ready, can be viewed in your browser if you know the relevant query id. Start from the /listQueries end point if you do not know the relevant query id.

That is, assuming that you uploaded a file containing a query which was assigned id 42 you can direct your browser to:

https://www.alertnessapi.com/v3/viewResult/42

to view it.