Skip to content

API Specifications

Jump to bottom
YeonJeong Kim edited this page Nov 17, 2023 · 28 revisions

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
{
    "id": int,
    "email": "string",
    "nickname": "string"
}
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 string favorite symbol ids

e.g. /symbol/favorite/backup/?id=18,1,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/ (backup user's custom symbols list(validate and delete)) 🔒

Request

Params
name Type Datatype Description
id optional string custom symbol ids

e.g. /symbol/enable/?id=18,1,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

Clone this wiki locally