Api design - SYSUMSC/hackreg-t1-backend GitHub Wiki

Convention

The format of names in an error of invalid arguments

Examples

{
  "message": "提供的信息不符合要求",
  "names": [
    "form",
    "form.teamInfo",
    "form.teamInfo.name",
    "form.memberInfo",
    "form.memberInfo[2].name"
  ]
}

Rules

  • The names are based on the response body format of /signup/fetch.
  • Use . to indicate the belonging relationship of two object.
  • Use [] to indicate the actual item among an array.

General

Invalid request method or path

  • Status: 400 (Bad Request)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "请求的方法或路径无效"
}

Auth

Register an account

Request

  • Method: POST
  • URL: /auth/register
  • Headers: Content-Type: application/json; charset=utf-8
  • Body(example):
{
  "email": "[email protected]",
  "password": "$LoveAndPeace$"
}
  • Arguments:
Name Type Description
email String The email of the account(must be in email format, max length=30)
password String The password of the account(must match [a-zA-Z0-9#@!~%^&*]{8,30})

Response

Register successfully

  • Status: 204 (Empty Response)
  • Header: Set-Cookie: [the cookie containing an JWT object]

Account with requested email already exists

  • Status: 409 (Conflict)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "指定邮箱的账户已经存在"
}

Invalid request body

  • Status: 400 (Bad Request)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "请求内容的JSON格式有误"
}

Invalid arguments

  • Status: 400 (Bad Request)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "提供的信息不合要求",
  "names": []
}
  • Arguments:
Name Type Description
message String The reason of the error
names String The name of invalid arguments

Access too frequent

  • Status: 429 (Too Many Requests)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "访问频率过高，请稍后再试"
}

Internal server error

  • Status: 500 (Internal Server Error)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "服务器内部出错"
}

Login to an account

Request

  • Method: POST
  • URL: /auth/login
  • Headers: Content-Type: application/json; charset=utf-8
  • Body(example):
{
  "email": "[email protected]",
  "password": "$LoveAndPeace$"
}
  • Arguments:
Name Type Description
email String The email of the account(must in email format, max length=30)
password String The password of the account(must match [a-zA-Z0-9#@!~%^&*]{8,})

Response

Log in successfully

  • Status: 204 (Empty Response)
  • Header: Set-Cookie: [the cookie containing an JWT object]

Incorrect email or password or the account does not exist

  • Status: 422 (Unprocessable Entity)
  • Body:
{
  "message": "指定的邮箱或密码不正确"
}

Invalid request body

  • Status: 400 (Bad Request)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "请求内容的JSON格式有误"
}

Invalid arguments

  • Status: 400 (Bad Request)
  • Headers: Content-Type:application/json; charset=utf-8
  • Body:
{
  "message": "提供的信息不合要求",
  "names": []
}
  • Arguments:
Name Type Description
message String The reason of the error
name String The names of invalid arguments

Access too frequent

There are two causes:

  1. The request with a certain pair of IP and email are being sent too frequently in a short time.
  2. The request with a certain IP are being sent too frequently in a relatively long time.
  • Status: 429 (Too Many Requests)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "访问频率过高，请稍后再试"
}

Internal server errror

  • Status: 500 (Internal Server Error)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "服务器内部出错"
}

Request to reset the password of an account

Request

  • Method: POST
  • URL: /auth/reset
  • Headers: Content-Type: application/json; charset=utf-8
  • Body(example):
{
  "email": "[email protected]"
}
  • Arguments:
Name Type Description
email String The email of captain(must in email format, max length=30)

Response

Email sent

  • Status: 204 (Empty Response)

Account with given email does not exist

  • Status: 404 (Not Found)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "该邮箱对应的账户不存在"
}

Invalid request body

  • Status: 400 (Bad Request)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "请求内容的JSON格式有误"
}

Invalid arguments

  • Status: 400 (Bad Request)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "提供的信息不合要求",
  "names": []
}
  • Arguments:
Name Type Description
message String The reason of the error
name String The names of invalid arguments

Access too frequent

  • Status: 429 (Too Many Requests)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "访问频率过高，请稍后再试"
}

Internal server error

  • Status: 500 (Internal Server Error)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "服务器内部出错"
}

Confirm to reset the password of an account

Request

  • Method: POST
  • URL: /auth/confirm
  • Headers: Content-Type: application/json; charset=utf-8
  • Body(example):
{
  "email": "[email protected]",
  "password": "$MinatoAqua$",
  "token": "a87d23jhrt480mu98fm9sa45nc8u956vnp2mc23r25si91rf4sdpv3gf0rh021"
}
  • Arguments:
Name Type Description
email String The email of captain(must in email format, max length=30)
password String The password of captain(must match [a-zA-Z0-9#@!~%^&*]{8,30})
token String The token of the operation(derived from the email sent by reset, length=64)

Response

Reset successfully

  • Status: 204 (Empty Response)

Invalid or expired token or the user didn't request to reset the password or the account does not exsist

  • Status: 400 (Bad Request)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "验证码无效或已过期，重置密码操作无效"
}

Invalid request body

  • Status: 400 (Bad Request)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "请求内容的JSON格式有误"
}

Invalid arguments

  • Status: 400 (Bad Request)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "提供的信息不合要求",
  "names": []
}
  • Arguments:
Name Type Description
message String The reason of the error
name String The names of invalid arguments

Access too frequent

  • Status: 429 (Too Many Requests)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "访问频率过高，请稍后再试"
}

Internal server error

  • Status: 500 (Internal Server Error)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "服务器内部出错"
}

Signup Form

Fetch the signup form

Request

  • Method: GET
  • URL: /signup/fetch

Response

Fetch successfully

  • Status: 200 (OK)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body(example):
{
  "confirmed": true,
  "form": {
    "teamInfo": {
      "name": "下北泽工农自卫队",
      "description": "这么臭的队有什么介绍的必要吗(直球)"
    },
    "memberInfo": [
      {
        "name": "田所浩二",
        "gender": "2",
        "captain": true,
        "email": "[email protected]",
        "phone": "11451419198",
        "size": "6",
        "school": "夏·北泽·雷普大学",
        "education": "2",
        "grade": "二年级",
        "profession": "雷普学",
        "experience": "哼哼，啊啊啊啊啊啊（发出世界人民大团结般的吼叫）"
      }
    ]
  }
}
  • Arguments:
Name Type Description
confirmed Boolean Specifies whether the form is confirmed.
form.teamInfo.name String The name of the team (max length=20)
form.teamInfo.description String The description of the team (max length=50)
form.memberInfo[].name String The name of each member (max length=12)
form.memberInfo[].gender String The gender of each member (0=male, 1=female, 2=other)
form.memberInfo[].captain Boolean Specifies whether the member is the captain (each team should have only one captain)
form.memberInfo[].email String The email of each member (must be in email format, max length=30)
form.memberInfo[].phone String The phone number of each member (must be in mainland China phone number format or HongKong one)
form.memberInfo[].size String The size of the cloth of each member (XS=0, S=1, M=2, L=3, XL=4, XXL=5, XXXL=6)
form.memberInfo[].school String The school name of each member(max length=15)
form.memberInfo[].education String The educational background of each member(本科生=0, 研究生=1, 其他=2)
form.memberInfo[].grade String The grade of each member(max length=10)
form.memberInfo[].profession String The profession of each member(max length=20)
form.memberInfo[].experience String The personal experience of each member(max length=100)

Unauthorized

  • Status: 403 (Forbidden)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "需要登录才能进行操作"
}

Invalid cookie (caused by the invalid JWT object inside)

  • Status: 400 (Bad Request)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "无法识别身份信息或身份信息已过期，请重新登录"
}

Invalid request body

  • Status: 400 (Bad Request)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "请求内容的JSON格式有误"
}

Access too frequent

  • Status: 429 (Too Many Requests)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "访问频率过高，请稍后再试"
}

Internal server error

  • Status: 500 (Internal Server Error)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "服务器内部出错"
}

Update the signup form

Request

  • Method: POST
  • URL: /signup/update
  • Headers: Content-Type: application/json; charset=utf-8
  • Body(example):
{
  "confirmed": true,
  "form": {
    "teamInfo": {
      "name": "下北泽工农自卫队",
      "description": "这么臭的队有什么介绍的必要吗(直球)"
    },
    "memberInfo": [
      {
        "name": "田所浩二",
        "gender": "2",
        "captain": true,
        "email": "[email protected]",
        "phone": "11451419198",
        "size": "6",
        "school": "夏·北泽·雷普大学",
        "education": "2",
        "grade": "二年级",
        "profession": "雷普学",
        "experience": "哼哼，啊啊啊啊啊啊（发出世界人民大团结般的吼叫）"
      }
    ]
  }
}
  • Arguments:
Name Type Description
confirmed Boolean Specifies whether the form is confirmed.
form.teamInfo.name String The name of the team (max length=20)
form.teamInfo.description String The description of the team (max length=50)
form.memberInfo[].name String The name of each member (max length=12)
form.memberInfo[].gender String The gender of each member (0=male, 1=female, 2=other)
form.memberInfo[].captain Boolean Specifies whether the member is the captain (each team should have only one captain)
form.memberInfo[].email String The email of each member (must be in email format, max length=30)
form.memberInfo[].phone String The phone number of each member (must be in mainland China phone number format or HongKong one)
form.memberInfo[].size String The size of the cloth of each member (XS=0, S=1, M=2, L=3, XL=4, XXL=5, XXXL=6)
form.memberInfo[].school String The school name of each member(max length=15)
form.memberInfo[].education String The educational background of each member(本科生=0, 研究生=1, 其他=2)
form.memberInfo[].grade String The grade of each member(max length=10)
form.memberInfo[].profession String The profession of each member(max length=20)
form.memberInfo[].experience String The personal experience of each member(max length=100)

Response

Update successfully

  • Status: 204 (Empty Response)

The signup has not been on

  • Status: 403 (Forbidden)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "报名尚未开始"
}

The signup has been over

  • Status: 403 (Forbidden)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "报名已经结束，不能再对报名表单做任何修改"
}

Invalid arguments

  • Status: 400 (Bad Request)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "提供的信息不合要求",
  "names": []
}
  • Arguments:
Name Type Description
message String The reason of the error
names String The names of invalid arguments

Unauthorized

  • Status: 403 (Forbidden)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "需要登陆才能进行操作"
}

Invalid cookie (caused by the invalid JWT object inside)

  • Status: 400 (Bad Request)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "无法识别身份信息或身份信息已过期，请重新登录"
}

Access too frequent

  • Status: 429 (Too Many Requests)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "访问频率过高，请稍后再试"
}

Internal server error

  • Status: 500 (Internal Server Error)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "服务器内部出错"
}

Submit

Submit the work file (.zip)

Request

  • Method: POST
  • URL: /submit
  • Headers: Content-Type: multipart/form-data
  • Body: [The .zip file]

Response

Submit successfully

  • Status: 204 (Empty Response)

The work submitting has not been on

  • Status: 403 (Forbidden)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "作品提交尚未开始"
}

The work submitting has been over

  • Status: 403 (Forbidden)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "作品提交已经截止"
}

The zip file reaches the size limit

  • Status: 400 (Bad Request)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "文件大小超过上限"
}

Invalid request (request body is not a single file)

  • Status: 400 (Bad Request)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "请求无效"
}

Invalid cookie (caused by the invalid JWT object inside)

  • Status: 400 (Bad Request)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "无法识别身份信息或身份信息已过期，请重新登录"
}

Internal server error

  • Status: 500 (Internal Server Error)
  • Headers: Content-Type: application/json; charset=utf-8
  • Body:
{
  "message": "服务器内部出错"
}