API Conventions

团队内部注：强烈建议「接口显示为URL」而非「接口显示为名称」。

Data Schemas

Schemas first. Then define APIs based on schemas.

Current schemas naming:
<xxx>: list <xxx>s.
<xxx_base>: only necessary fields
<xxx_detail>: list one <xxx> detailedly

Avoid null if [], "" are enough, to keep a singular type. Use null only when necessary, for example when the integer value doesn't exist and it's reasonable not to omit it.

For all string values, there should be a length limit. Similarly, there should be a size limit on file value.

API URL

By default, use plural.

Singular: 0 or 1, exists or not. Like "current user".

API Responce

success

Return data directly.

Only use HTTP status code 200.

Separate retrieval of simple JSON data and relatively big data. What "relatively big data" means:

1.
Files. Except small text content, if suitable.
2.
Data that needs explicit sort/limit etc.

error

Use HTTP status codes first to make a satisfying classification.

400, 401, 403, 404, 422.
500

For convenience, some obvious responce can be omitted in docs, like 401, 403, 404 in many cases.

If status codes are not concrete enough, add code item to clarify, which is a concise and human-readable string enum.

If needed, more items like detail(string) can be added for convenience in debugging.

The above compose an error object. If there are more than one errors, return the first one.

Data Schemas#

API URL#

API Responce#

success#

error#

Data Schemas

API URL

API Responce

success

error