API设计思路

对于开发者来说，如果需要使用的API的设计富有逻辑性，可以根据常理去推导，将会非常有助于开发。

因此在这里谈谈 Orange Juice 中关于API的设计思路，让开发者能有一个大体上的认识。

ObjectID

直接继承 MongoDB 的设计，使用一个长 Hash 值来标识一个对象。在API中常以_id 出现，或者在以各种以 Id结尾的量中。

例如：

_id
userId        // User ID
problemId     // Problem ID
problemListId // ProblemList ID
submissionId  // Submission ID

URL & Method

URL 与 Method 采用经典的 REST 式设计。

在HTTP中常用的Method有如下4种：

• GET ：对资源的只读访问
• POST ：创建一个资源
• PUT：更新一个资源
• DELETE：删除一个资源

实际上，这就是对某资源的增删改查(CRUD)。

URL的设计则体现了资源的逻辑结构。

例如：

GET /user 表示检索用户；POST /user 表示创建用户。

Response

错误码

在响应正文中，至少包含一个错误码 code 。

• 当一切正常时，其值为0。

• 如果出现没有识别的错误(BUG)，其值为1。

  这种情况下，说明系统出现了错误，请提交这个问题给我们，十分感谢！

• 如果出现已经识别的错误，其值为一个质数，含义见下表。

  错误码	含义	备注
  2	Validation Error (验证失败)	有缺少的项或者非法数据
  3	Data Duplicated (数据重复)	如用户名重名等
  5	Wrong Passport (凭证错误)	用户名或密码错误等
  7	Permission Denied (权限不足)
  11	Resource Unavailable (资源不可用)	资源不存在等

当 code 不为 0 时，一般还会携带一个 msg 域来进一步阐述问题发生的原因。

实体

除了错误码以外，响应正文中还将包含若干实体，它们可能是：

userId
user
users

problemId
problem
problems

problemListId
problemList
problemLists

submissionId
submission
submissions

以 Id 结尾的是 ObjectID ；单数/复数形式对应实体的单数/复数(数组)。

响应返回的是最新的实体的状态。

例如创建、更新用户之后，都会返回新的 user ；

例如创建提交之后，会返回新的 submission 与 problemList ，因为这两个实体都发生了变化。

Request

Request 除了需要携带必要的 Cookie，即 SessionID 以外，有 params、query 与 body 三个参数存在的地方。

params 与 query 直接从 URL 中解析，而 body 需要从请求正文中解析。

GET 请求是没有 body 部分的，只能通过 params 与 query 来完成查询。

Params

一般来说，params 中的参数与要操作的实体的逻辑结构有关，一般都是 ObjectID 格式的。

例如：

GET /user/:userId 定义下，GET /user/58617add5f0fd333c3e97467 表示查询用户58617add5f0fd333c3e97467 的资料。

Query

一般来说，query 与筛选、条件有关，在查询复数实体的时候，通常有 limit 与 skip 这两项，用于控制查询得到的文档数量。

Body

一般来说，请求正文的格式没有什么固定的套路。