Website In Development
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
- 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;
- 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;
- 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.
- If
Endpoints
A primary web browser endpoints are:
/v3
– Currently, just redirects to/v3/jsonupload
/v3/jsonupload
– web-form to upload ajson
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.