interface

interface

interface 服务是向外网开放的部分，是前后端分离设计中的后端部分，设计上面向浏览器，因此并不按照 REST 规范实现。服务会保存 Cookie 用来识别用户。

针对一切接口的约定

大部分接口的 Request 和 Response 默认均为 JSON 格式，另有明确规定的例外。“返回值”仅表示在请求合法时的可能返回值；不合法的请求的返回值是未定义 的，例如可能为 400，也可能请求成功。除此之外，所有请求均可能失败或者返回 5xx 错误，表示网络错误或服务器内部错误，此时的行为也是未定义的。

对于 JSON 格式的返回值，均包含 success: bool，表示请求是否成功。如果请求不成功，则视为失败，原因会在 message: string 中列出，这条消息应该 直接展示给用户，不应该由脚本进行识别。

API 描述中用 req 表示请求内容，resp 表示返回内容。

POST /api/register

• 请求类型：application/json
• 返回值：
• • 204 No Content 表示请求成功

注册一个新用户。用户不能处于已登录状态，用户名 req.username: string 不能和已有用户重名，且必须满足正则表达式 [0-9A-Za-z_]{3,16}。密码 req.password: string 不能为空，长度须在 32 字符以内，必须为 ASCII 字符。目前后端仅要求密码非空，除此之外对密码暂时没有限制。

请求示例：

{
    "username": "username",
    "password": "<password>"
}

POST /api/login

• 请求类型：application/json
• 返回值：
• • 204 表示请求成功

登录用户。用户名 req.username: string 和密码 req.password: string 须和注册时填入的用户名和密码一致，且不能处于登录状态。

请求示例：

{
    "username": "username",
    "password": "<password>"
}

POST /api/problem/new

• 需要登录
• 请求类型：text/xml
• 返回值：
• • 200 表示请求成功

创建一道新题目。需保证输入的 XML 文件合法，根标签为 <Problem> 且符合 schema。请求成功时返回的 resp 保证 resp.problem_id: string 表示创建的题目的 problem_id.

GET /api/problem/id/:problem_id/statement

• 返回值：
• • 200 表示请求成功
• • 404 表示没有 problem_id 对应的题目

获取一道题目的题面。

POST /api/problem/upload-temp

• 请求类型：无限制
• 返回值：
• • 200 表示请求成功

上传一个临时文件，供其他 API 使用。文件大小不能超过 128MB。请求成功时返回的 resp 保证 resp.file_id: string 表示临时文件的文件名。

POST /api/problem/id/:problem_id/upload-data

• 请求类型：application/json
• 返回值：
• • 204 表示请求成功

从 req.zip_file_id: string 的文件名上传题目数据文件，该文件必须是 zip 格式，文件名不能为 . 或 ..，且当前用户必须是 题目的创建者。文件大小及解压后的总大小不能超过 128MB，且总文件个数不能超过 1000 个。

请求示例：

{
    "zip_file_id": "..."
}

POST /api/problem/id/:problem_id/delete-data

• 请求类型：无
• 返回值：
• • 204 表示请求成功

删除题目的所有数据文件。

POST /api/problem/id/:problem_id/submit

• 请求类型：text/xml
• 返回值：
• • 200 表示请求成功

创建一个提交。xml 的根节点必须是 <JudgeRequest> 且必须符合 schema。请求成功时返回的 resp 保证 resp.submission_id: string 对应本次提交的 ID.