API Specifications

API Specifications for SpeechBuddy

• Template adopted from: https://gist.github.com/azagniotov/a4b16faf0febd12efbc6c3d7370383a6

---

User

POST /user/signup/ (creates new user by signing up)

Request

Header

Key	Value	Description
None	None	N/A

Body

{
  "email": "string",
  "password": "string",
  "nickname": "string"
}

Response

Status Code

Code	key of Message	Description
201	None	Successfully created
400	email	missing input value, blank input, invalid email format, length error(✅len<=50)
400	already_taken	email is already taken by another user
400	password	missing input value, blank input
400	short_pw	short password length(✅len>=8)
400	nickname	missing input value, blank input, length error(✅len<=15)

POST /user/validateemail/signup/send/ (sends verification code for signup via email)

Request

Header

Key	Value	Description
None	None	N/A

Body

{
  "email": "string"
}

Response

Status Code

Code	key of Message	Description
200	None	N/A (successfully sent)
400	email	missing input value, blank input, invalid email format, length error(✅len<=50)
400	already_taken	email is already taken by another user

POST /user/validateemail/pw/send/ (sends verification code for forgot-pw via email)

Request

Header

Key	Value	Description
None	None	N/A

Body

{
  "email": "string"
}

Response

Status Code

Code	key of Message	Description
200	None	N/A (successfully sent)
400	email	missing input value, blank input, invalid email format, length error(✅len<=50)
400	no_user	no such user w/ the email

POST /user/validateemail/signup/accept/ (checks email verification code for signup)

Request

Header

Key	Value	Description
None	None	N/A

Body

{
  "email": "string", // should be automatically set by frontend! not by a user!
  "code": "string"
}

Response

Status Code

Code	key of Message	Description
200	None	N/A (successfully checked)
400	email	missing input value, blank input, invalid email format, length error(✅len<=50)
400	code	missing input value, blank input, length error(✅len==6)
400	fail	wrong code

POST /user/validateemail/pw/accept/ (checks email verification code for forgot-pw)

Request

Header

Key	Value	Description
None	None	N/A

Body

{
  "email": "string", // should be automatically set by frontend! not by a user!
  "code": "string"
}

Response

Body

{
  "access": "string"
}

Status Code

Code	key of Message	Description
200	None	N/A (successfully checked)
400	email	missing input value, blank input, invalid email format, length error(✅len<=50)
400	code	missing input value, blank input, length error(✅len==6)
400	fail	wrong code

POST /user/login/ (creates new authorization tokens)

Request

Header

Key	Value	Description
None	None	N/A

Body

{
  "email": "string",
  "password": "string"
}

Response

Body

{
  "access": "string",
  "refresh": "string"
}

Status Code

Code	key of Message	Description
200	None	OK
400	email	missing input value, blank input, invalid email format
400	wrong_email	no such user w/ the email
400	password	missing input value, blank input
400	wrong_password	wrong password for the email

POST /user/refresh/ (refreshes user's authorization tokens)

Request

Header

Key	Value	Description
None	None	N/A

Body

{
  "refresh": "string"
}

Response

Body

{
  "access": "string"
}

Status Code

Code	key of Message	Description
200	None	OK
400	refresh	missing input value, blank input
401	detail and code	refresh token expired; user has to attempt a new login

POST /user/logout/ (deletes user's authorization tokens) 🔒

Request

Header

Key	Value	Description
Authorization	Bearer {access}	user's access token (must be sent with the prefix 'Bearer')

Body

{
  "refresh": "string"
}

Response

Status Code

Code	key of Message	Description
200	None	OK
400	refresh	missing input value, blank input
403	detail	no access token was sent in the header
403	detail, code and messages	access token expired; user has to refresh to retrieve a new token

GET /user/profile/ (gets user's profile) 🔒

Request

Header

Key	Value	Description
Authorization	Bearer {access}	user's access token (must be sent with the prefix 'Bearer')

Response

Body

{
  "user": {
    "id": int,
    "email": "string",
    "nickname": "string",
    "updated_at": timestamp
    ... // more fields to be added later
  }
}

Status Code

Code	key of Message	Description
200	None	OK
403	detail	no access token was sent in the header
403	detail, code and messages	access token expired; user has to refresh to retrieve a new token

PATCH /user/profile/nickname/ (changes user's nickname) 🔒

Request

Header

Key	Value	Description
Authorization	Bearer {access}	user's access token (must be sent with the prefix 'Bearer')

Body

{
  "nickname": "string"
}

Response

Status Code

Code	key of Message	Description
200	None	Successfully changed
400	nickname	missing input value, blank input, length error(✅len<=15)
400	same	same as the original nickname

PATCH /user/profile/password/ (changes user's password) 🔒

Request

Header

Key	Value	Description
Authorization	Bearer {access}	user's access token (must be sent with the prefix 'Bearer')

Body

{
  "password": "string"
}

Response

Status Code

Code	key of Message	Description
200	None	Successfully changed
400	password	missing input value, blank input, length error(✅len>=8)
400	short_pw	short password length(✅len>=8)

POST /user/withdraw/ (deletes user's account) 🔒

Request

Header

Key	Value	Description
Authorization	Bearer {access}	user's access token (must be sent with the prefix 'Bearer')

Body

{
  "refresh": "string"  // to be revoked
}

Response

Status Code

Code	key of Message	Description
200	None	OK (successfully deleted)
400	refresh	missing input value, blank input
403	detail	no access token was sent in the header
403	detail, code and messages	access token expired; user has to refresh to retrieve a new token

---

Symbol

POST /symbol/favorite/backup/ (backup user's favorite symbols) 🔒

Request

Params

name	Type	Datatype	Description
id	optional	int	favorite symbol ids

e.g. /symbol/favorite/backup/?id=18&id=1&id=2

Header

Key	Value	Description
Authorization	Bearer {access}	user's access token (must be sent with the prefix 'Bearer')

Response

Status Code

Since multiple parameters can be passed, "message" field is also a list when id raises an error

Code	key of Message	Description
200	None	OK
400	id	missing input value, blank input, no such symbol
400	not_mine	the requested symbol is created by another user
403	detail	no access token was sent in the header
403	detail, code and messages	access token expired; user has to refresh to retrieve a new token

GET /symbol/favorite/backup/ (get user's favorite symbols) 🔒

Request

Header

Key	Value	Description
Authorization	Bearer {access}	user's access token (must be sent with the prefix 'Bearer')

Response

{
  "results": [
    {
      "id": int  // symbol id
    },
    {
      "id": int
    }...
  ]
}

Status Code

Code	key of Message	Description
200	None	OK
403	detail	no access token was sent in the header
403	detail, code and messages	access token expired; user has to refresh to retrieve a new token

POST /symbol/backup/ (backup user's symbol) 🔒

Request

Header

Key	Value	Description
Authorization	Bearer {access}	user's access token (must be sent with the prefix 'Bearer')

Body

multipart/form-data

"text" : string
"category" : int
"image" : image file

Response

{
  "id": int  // symbol id
}

Status Code

Code	key of Message	Description
200	None	OK
400	text	missing input value, blank input
400	long_text	word text is too long
400	category	missing input value, blank input, invalid category
400	image	missing input value
403	detail	no access token was sent in the header
403	detail, code and messages	access token expired; user has to refresh to retrieve a new token

GET /symbol/ (get all of the user's valid custom symbols) 🔒

Request

Header

Key	Value	Description
Authorization	Bearer {access}	user's access token (must be sent with the prefix 'Bearer')

Response

{
   "my_symbols": [
       {
           "id": int,
           "text": string,
           "category": int,
           "image": string(image url),
           "created_at": string(datetime)
       },
       {
           "id": int,
           "text": string,
           "category": int,
           "image": string(image url),
           "created_at": string(datetime)
       }...
   ]
}

Status Code

Code	key of Message	Description
200	None	OK
403	detail	no access token was sent in the header
403	detail, code and messages	access token expired; user has to refresh to retrieve a new token

GET /symbol/int:pk/ (get user's specific custom symbol) 🔒

pk is the symbol_id(int)

Request

Header

Key	Value	Description
Authorization	Bearer {access}	user's access token (must be sent with the prefix 'Bearer')

Response

{
   "my_symbol": {
      "id": int, // same as the pk value
      "text": string,
      "category": int,
      "image": string(image url),
      "created_at": string(datetime)
    }
}

Status Code

Code	key of Message	Description
200	None	OK
400	pk	no such symbol
400	not_mine	the requested symbol is created by another user
400	invalid	the symbol is not valid yet(is_valid==False)
403	detail	no access token was sent in the header
403	detail, code and messages	access token expired; user has to refresh to retrieve a new token

POST /symbol/enable/ (validate user's custom symbols) 🔒

Request

Params

name	Type	Datatype	Description
id	optional	int	custom symbol ids

e.g. /symbol/enable/?id=18&id=1&id=2

Header

Key	Value	Description
Authorization	Bearer {access}	user's access token (must be sent with the prefix 'Bearer')

Response

Status Code

Since multiple parameters can be passed, "message" field is also a list when id raises an error

Code	key of Message	Description
200	None	OK
400	id	missing input value, blank input, no such symbol, default symbol
400	not_mine	the requested symbol is created by another user
403	detail	no access token was sent in the header
403	detail, code and messages	access token expired; user has to refresh to retrieve a new token

---

Setting

POST /setting/backup/ (backup user's setting) 🔒

Request

Header

Key	Value	Description
Authorization	Bearer {access}	user's access token (must be sent with the prefix 'Bearer')

Body

{
  "display_mode": int,
  "default_menu": int
}

Response

Status Code

Code	key of Message	Description
200	None	OK
400	display_mode	missing input value, blank input, invalid mode
400	default_menu	missing input value, blank input, invalid menu
403	detail	no access token was sent in the header
403	detail, code and messages	access token expired; user has to refresh to retrieve a new token

GET /setting/backup/ (get user's setting) 🔒

Request

Header

Key	Value	Description
Authorization	Bearer {access}	user's access token (must be sent with the prefix 'Bearer')

Response

Body

{
  "display_mode": int,
  "default_menu": int
}

Status Code

Code	key of Message	Description
200	None	OK
403	detail	no access token was sent in the header
403	detail, code and messages	access token expired; user has to refresh to retrieve a new token