API version 1¶

GET /users¶

A list of all users - requires admin or researcher authorization.

Example request:

GET /users HTTP/1.1
Host: textscroll.cs.hmc.edu
Authorization: Credential=alsdkfjqeprt798sdhvzxkfnioq34ruaps98dfyaskjcan

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "users": [
        "user1",
        "user2",
        "user3"
    ]
}

Request Headers:
	Authorization – encrypted token for authentication, or a username/password combo
Status Codes:	200 OK – no error 401 Unauthorized – not an authenticated administrator or researcher

POST /users/create_user¶

Creates a new user user_id with the application, logs them in, and returns a token to be used for future authentication.

Example request:

POST /users/create_user
Host: textscroll.cs.hmc.edu
Content-Type: application/x-www-form-urlencoded

username=MyNewUserName&password=SuPeRH@x0rPa$$w()rD

Example response:

HTTP/1.1 201 Created
Vary: Accept
Content-Type: application/json
Location: https://textscroll.cs.hmc.edu/api/v1/users/MyNewUserName

token=alsdkfjqeprt798sdhvzxkfnioq34ruaps98dfyaskjcan

Status Codes:	201 Created – The user was successfully created 400 Bad Request – The username is malformed (i.e. invalid) 409 Conflict – The given username exists

GET /users/(string: user_id)¶

Gets information about user_id.

Example request:

GET /users/MyUserName
Host: textscroll.cs.hmc.edu

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
   "username": "MyUserName",
   "trials": [
      1,
      3,
      11
   ],
   "library": [
      "The Once and Future King",
      "A Brief History of Time"
   ],
   "settings": {
      "FontSize": "Large",
      "FontColor": "Black",
      "Theme": "Light"
   }
}

Status Codes:	200 OK – The user could be found 400 Bad Request – The username is malformed 404 Not Found – The user does not exist

POST /users/(string: user_id)/authenticate¶

Authenticates user_id.

Example request:

POST /users/MyUserName/authenticate
Host: textscroll.cs.hmc.edu
Authorization: Credential=SuPeRH@x0rPa$$w()rD

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "authenticated": true
}

Request Headers:
	Authorization – Authorization for the request in the form of the user’s password.
Status Codes:	200 OK – User was authenticated correctly 400 Bad Request – The username is malformed 404 Not Found – User does not exist

POST /users/(string: user_id)/change_password¶

Changes user_id‘s password, invalidates all existing sessions, and returns a new valid session token.

Example request:

POST /users/MyUserName/change_password
Host: textscroll.cs.hmc.edu
Authorization: Credential=SuPeRH@x0rPa$$w()rD

new_password=XxXtr4SuPeRH@x0rPa$$w()rD

Example Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
   "password_changed": true,
   "new_token": oqwe879fasokdljfqnl3o4fi7asicvqjwek
}

Request Headers:
	Authorization – Authorization for the request - a token or password
Status Codes:	200 OK – Password was successfully changed 400 Bad Request – The username is malformed 400 Bad Request – The password was invalid 400 Bad Request – The new password is invalid 404 Not Found – User does not exist

GET /users/(string: user_id)/trials¶

Returns a list of the trial-ids that user_id had participated in.

Requires administrator or researcher credentials.

Example Request:

GET /users/MyUserName/trials
Host: textscroll.cs.hmc.edu
Authorizaton: Credential=s0upersecrett0ken

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "trials": [
      1,
      3,
      11
   ],
}

Request Headers:
	Authorization – Authorizes the user for this request - must be an administrator or researcher credential
Status Codes:	200 OK – The trials were returned 400 Bad Request – The username was malformed 401 Unauthorized – Not an administrator or researcher 404 Not Found – User does not exist

GET /users/(string: user_id)/trials/(int: trial_id)¶

Returns the trial for user user_id and trial trial_id

Requires administrator or researcher credentials.

Example Request:

GET /users/MyUserName/trials/1
Host: textscroll.cs.hmc.edu
Authorizaton: Credential=s0upersecrett0ken

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   1: {
      "trial_data": "stuff",
      "other_data": "other_stuff"
   }
}

Request Headers:
	Authorization – Authorizes the user for this request - must be an administrator or researcher credential.
Status Codes:	200 OK – The trial was returned 400 Bad Request – The username was malformed 400 Bad Request – The trial doesn’t exist for this user 401 Unauthorized – Not an administrator or researcher 404 Not Found – User does not exist 404 Not Found – Trial does not exist

GET /users/(string: user_id)/settings¶

Returns the settings for user_id.

Example Request:

GET /users/MyUserName/settings
Host: textscroll.cs.hmc.edu
Authorizaton: Credential=s0upersecrett0ken

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "settings": {
      "FontSize": "Large",
      "FontColor": "Black",
      "Theme": "Light"
   }
}

Request Headers:
	Authorization – Authorizes the user for this request - can be a token or a password.
Status Codes:	200 OK – The settings could be found 400 Bad Request – The username was malformed 401 Unauthorized – User is not authenticated 404 Not Found – User does not exist

GET /users/(string: user_id)/settings/(string: setting_id)¶

Returns the setting value of setting_id for user_id.

Example Request:

GET /users/MyUserName/settings/FontSize
Host: textscroll.cs.hmc.edu
Authorizaton: Credential=s0upersecrett0ken

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "FontSize": "Large"
}

Request Headers:
	Authorization – Authorizes the user for this request - can be a token or a password.
Status Codes:	200 OK – The setting was valid and had a value 400 Bad Request – The username was malformed 400 Bad Request – The setting does not exist 401 Unauthorized – User is not authenticated 404 Not Found – User does not exist

POST /users/(string: user_id)/settings/(string: setting_id)¶

Sets the value of setting_id for user_id.

Example Request:

POST /users/MyUserName/settings/FontSize
Host: textscroll.cs.hmc.edu
Authorizaton: Credential=s0upersecrett0ken

FontSize=Small

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "FontSize": "Small"
}

Request Headers:
	Authorization – Authorizes the user for this request - can be a token or a password.
Status Codes:	200 OK – The setting could be updated 400 Bad Request – The username was malformed 400 Bad Request – The setting does not exist 401 Unauthorized – User is not authenticated 404 Not Found – User does not exist

GET /users/(string: user_id)/library¶

Get user_id‘s text library.

Example Request:

GET /users/MyUserName/library
Host: textscroll.cs.hmc.edu
Authorizaton: Credential=s0upersecrett0ken

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "library": [
      "The Once and Future King",
      "A Brief History of Time"
   ]
}

Request Headers:
	Authorization – Authorizes the user for this request - can be a token or a password.
Status Codes:	200 OK – The library was returned. 400 Bad Request – The username was malformed 401 Unauthorized – User is not authenticated 404 Not Found – User does not exist

GET /users/(string: user_id)/library/(string: text_id)¶

Get the text associated with text_id from user_id‘s text library.

Example Request:

GET /users/MyUserName/library/The%20Once%20and%20Future%20King
Host: textscroll.cs.hmc.edu
Authorizaton: Credential=s0upersecrett0ken

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "bookmarks": [30, 80, 117],
   "title": "The Once and Future King",
   "pages": "lots",
   "last page read": 3,
   "preview": "...excerpt...",
   "contents": Object(compressed_contents)
}

Request Headers:
	Authorization – Authorizes the user for this request - can be a token or a password.
Status Codes:	200 OK – The text was returned 400 Bad Request – The username was malformed 401 Unauthorized – User is not authenticated 404 Not Found – User does not exist 404 Not Found – The text does not exist

POST /users/(string: user_id)/library/(string: text_id)¶

Add a text to user_id‘s library with text_id name.

Example Request:

POST /users/MyUserName/library/The%20Once%20and%20Future%20King
Host: textscroll.cs.hmc.edu
Authorizaton: Credential=s0upersecrett0ken

title=The%20Once%20and%20Future%20King&bookmarks=30,80,117

Example Response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://textscroll.cs.hmc.edu/api/v1/users/MyUserName/library/The%20Once%20and%20Future%20King

Request Headers:
	Authorization – Authorizes the user for this request - can be a token or a password.
Status Codes:	201 Created – The text was created 400 Bad Request – The username was malformed 400 Bad Request – The text was malformed 401 Unauthorized – User is not authenticated 404 Not Found – User does not exist

GET /users/(string: user_id)/library/(string: text_id)/(string: text_attr)¶

Get the attribute named by text_attr of the text text_id in user_id‘s library.

Example Request:

GET /users/MyUserName/library/The%20Once%20and%20Future%20King/title
Host: textscroll.cs.hmc.edu
Authorizaton: Credential=s0upersecrett0ken

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "title": "The Once and Future King"
}

Request Headers:
	Authorization – Authorizes the user for this request - can be a token or a password.
Status Codes:	200 OK – The attribute was found 400 Bad Request – The username was malformed 400 Bad Request – The text name was malformed 400 Bad Request – The attribute is invalid 401 Unauthorized – User is not authenticated 404 Not Found – User does not exist 404 Not Found – Text does not exist

POST /users/(string: user_id)/library/(string: text_id)/(string: text_attr)¶

Set the attribute named by text_attr of the text text_id in user_id‘s library.

Example Request:

POST /users/MyUserName/library/The%20Once%20and%20Future%20King/title
Host: textscroll.cs.hmc.edu
Authorizaton: Credential=s0upersecrett0ken

title=The%20once%20and%20Future%20King

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "original": "The Once and Future King",
   "updated": "The once and Future King"
}

Request Headers:
	Authorization – Authorizes the user for this request - can be a token or a password.
Status Codes:	200 OK – The attribute was found 400 Bad Request – The username was malformed 400 Bad Request – The text name was malformed 400 Bad Request – The attribute is invalid 400 Bad Request – The value was invalid 401 Unauthorized – User is not authenticated 404 Not Found – User does not exist 404 Not Found – Text does not exist

GET /trials¶

Get all trials that have been conducted, and the user who performed them.

Requires administrator or researcher credentials.

Example Request:

GET /trials
Host: textscroll.cs.hmc.edu
Authorizaton: Credential=s0upersecrett0ken

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   1: "MyUserName",
   2: "SomeOtherUserName",
   ...
}

Request Headers:
	Authorization – Authorizes the user for this request - can be a token or a password.
Status Codes:	200 OK – The trials were returned 401 Unauthorized – User is not authenticated

GET /trials/(int: trial_id)¶

Get the trial with an id of trial_id.

Requires administrator or researcher credentials.

Example Request:

GET /trials/13
Host: textscroll.cs.hmc.edu
Authorizaton: Credential=s0upersecrett0ken

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "trial_data": "stuff",
   "other_data": "other_stuff",
   "user_id": "MyUserName"
}

Request Headers:
	Authorization – Authorizes the user for this request - can be a token or a password.
Status Codes:	200 OK – The trials were returned 401 Unauthorized – User is not authenticated 404 Not Found – The trial doesn’t exist

POST /trials/(int: trial_id)¶

Set the trial with an id of trial_id.

Requires administrator or researcher credentials.

Example Request:

POST /trials/13
Host: textscroll.cs.hmc.edu
Authorizaton: Credential=s0upersecrett0ken

trial_data=stuff&other_data=other_stuff&user_id=MyUserName

Example Response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://textscroll.cs.hmc.edu/api/v1/trials/13

Request Headers:
	Authorization – Authorizes the user for this request - can be a token or a password.
Status Codes:	201 Created – The trial was created 400 Bad Request – No username indicated, or invalid username 401 Unauthorized – User is not authenticated

API version 1¶

Related Topics

This Page