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:
- Files. Except small text content, if suitable.
- 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.