Skip to content
This repository has been archived by the owner on Mar 20, 2021. It is now read-only.

Latest commit

 

History

History
216 lines (144 loc) · 7.49 KB

API_Specification.md

File metadata and controls

216 lines (144 loc) · 7.49 KB
Raw


API Specification


Base URL: mhml.greenberg.io

Note: This specification refers heavily to objects defined in the Data Specification.

Users Collection :

GET /api/users

Required: None

Response code Response body
200 Ok {'usernames': [array of usernames]}
  • This request retrieves a complete list of usernames stored in the database.
  • Note: the array could be empty.

POST /api/users

Required:

  • 'username' key of the User object.
  • The User JSON object must be enclosed into the outer-most key 'User'
Response code Response body
201 Created {'new user': User object}
409 Conflict {"error": "User <username> already exists"}

This request adds a new User object to the database.

User Resource

GET /api/users/<username>

Required: None

Response code Response body
200 Ok User object
404 Not Found {"error": "User <username> not found"}
  • This request retrieves a single User object registered with username <username>.
  • If no such user exists, a 404 error is thrown.

DELETE /api/users/<username>

Required: username key of the User object.

Response code Response body
204 No Content None
404 Not Found {"error": "User <username> not found"}
  • This request deletes the User object registered with username <username> from the database.
  • If no such user exists, a 404 error is thrown.

Sessions Collection :

GET /api/users/<username>/sessions

Required: None

Response code Response body
200 Ok {"session_ids": [array of session ids]}
404 Not Found {"error": "User <username> not found"}
  • This request retrieves a complete list of session ids stored in the database for a particular user.
  • Note: the array could be empty.
  • If no such user exists, a 404 error is thrown.

POST /api/users/<username>/sessions

Required: the following keys of the Session object are required:

  • "session_id"
  • "firmwareRevision"
  • "selfReported"
  • "ppg"
  • "gsr"
  • The Session JSON object must be enclosed into the outer-most key 'Session'

Each of the keys' value must be of the correct type according to the Data Specification.

Response code Response body
201 Created {"user": User Object,"new session": Session Object}
409 Conflict {"error": "Session ID <session_id> for user <username> already exists"}
404 Not Found {"error": "User <username> not found"}
400 Bad Request {"message": {<some_objec_key>: "Wrong or missing entry"}
  • This request adds a new Session object to the database (linked to some user) through <username>.
  • If a Session object in the database has the same <session_id> as the one in request body, a 409 error is thrown.
  • If no user registered with <username> is found, a 404 error is thrown.
  • If the request body does not comply with the Session object as defined in Data Specification, a 400 error is thrown.

Session Resource

GET /api/users/<username>/sessions/<session_id>

Required: None

Response code Response body
200 Ok Session object
404 Not Found {"error": "User <username> not found"}
{"error": "Session ID <session_id> for user <username> not found"}
  • This request retrieves a single Session object registered with id <session_id>, linked to a particular user.
  • If no such user exists, a 404 error is thrown.
  • Similarly, if the user exists but has no Session object under <session_id>, a 404 error is thrown.

POST /api/users/<username>/sessions/<session_id>

Required: the following keys of the Session object are required:

  • "session_id"
  • "firmwareRevision"
  • "selfReported"
  • "ppg"
  • "gsr"
  • "session_id" key of a Session object.
  • The Session JSON object must be enclosed into the outer-most key 'Session'

Each of the keys’ value must be of the correct type according to the Data Specification. Note that the request body parameter "session_id" and the URL parameter <session_id> must match.

Response code Response body
200 Ok {"user": User Object, "session_id": <session_id>, "updated": new Session Object}
404 Not Found {"error": "User <username> not found"}
{"error": "Session ID <session_id> for user <username> not found"}
400 Bad Request {"message": {<some_objec_key>: "Wrong or missing entry"}
{"error": "Session ID argument "session_id" does not match with URL session ID <session_id>"}
  • This request updates the Sesssion object with id <session_id> belonging to user with username <username>.
  • If no user registered with <username> is found, a 404 error is thrown.
  • Similarly, if the user exists but has no Session object under <session_id>, a 404 error is thrown.

DELETE /api/users/<username>/sessions/<session_id>

Required: None

Response code Response body
204 No Content None
404 Not Found {"error": "User <username> not found"}
{"error": "Session ID <session_id> for user <username> not found"}
  • This request deletes the Session object registered with id <session_id> linked to the user with username <username> from the database.
  • If no such user exists, a 404 error is thrown.
  • Similarly, if the user exists but has no Session object under <session_id>, a 404 error is thrown.
  • If the request body does not comply with the Session object as defined in Data Specification, a 400 error is thrown.

Training Resource

POST /api/train/users/<username>

Required: None

Response code Response body
200 Ok None
404 Not Found {"error": "User <username> not found"}
  • This request trains a Machine Learning model for the user registered under <username>, given its associated data in the database and saves it on the server as a separate pikle (.pkl) file.
  • If no such user exists, a 404 error is thrown.

Training Resource

POST /api/train/users/<username>

Required: None

Response code Response body
200 Ok None
404 Not Found {"error": "User <username> not found"}
  • This request trains a Machine Learning model for the user registered under <username>, given its associated data in the database and saves it on the server as a separate pikle (.pkl) file.
  • If no such user exists, a 404 error is thrown.

Classification Resource

GET /api/classify/users/<username>/sessions/<session_id>

Required: None

Response code Response body
200 Ok {"user": "<username>", "session_id": "<session_id>", "prediction": prediction}
404 Not Found {"error": "User <username> not found"}
{"error": "Session ID <session_id> for user <username> not found"}
  • This request asks for a stress score (a prediction) for a particular session of a particular user, making use of the user-specific pikle model.
  • If no such user exists, a 404 error is thrown.
  • Similarly, if the user exists but has no Session object under <session_id>, a 404 error is thrown.