HTTP API接口规范

1 概述
本文档简要介绍了一些 HTTP + JSON 的 API 设计实践。
1.1 名词
简称 全称 备注
HTTP Hyper Text Transfer Protocol 超文本传输协议
HTTPS
Hyper Text Transfer Protocol
over Secure Socket Layer
以安全为目标的 HTTP 通道
REST Representational State Transfer 表述性状态传递
JSON JavaScript Object Notation 一个轻量级的数据交换格式，它易于人类读写也易于及其解析生成

2 API 设计规范
2.1 基础
2.1.1 信息各部分要各司其职
一组对应的请求和响应用来标识一个特定的资源，各部分职责如下：
信息部分 职责
url path 标识资源 ID
body 内容
headers 所有请求通用的 metadata
query string 某特定请求的特定参数
2.1.2 强制使用 HTTPS
必须使用 HTTPS，无论任何场景和需求。
2.1.3 务必指定版本号
所有请求都必须指定版本号，例如使用 URLPath 指定：
GET /v1/bookings/ HTTP/1.1
Host: example.com
Accept: application/json
推荐使用 Accept Header 来提供版本号。
2.1.4 Media Type 必须使用 JSON
除特殊情况外，比如传输文件等，所有请求和响应必须使用 Content-Type: application/json 。
2.1.5 Encoding 必须使用 UTF-8
必须使用 utf-8 编码格式。
2.2 请求
2.2.1 资源名
资源路径名称务必使用复数，除非特定唯一的资源，比如系统介绍 url 可能为 “/about”，其他正常
情况例子：
用户列表 “/users”
用户详情 “/users/{user_id}/”
2.2.2 url path 要小写
Url path 必须使用小写字母，并用 “-” 分隔路径名字，比如 “device-charts”。
2.2.3 url path 中名词含义要清晰
不要出现缩写或者表述不明确的名词，url 应该清晰表述出它本身的作用。
2.3 响应
2.3.1 返回规范的状态码
成功
200：请求成功
201：资源创建成功
204：无数据
客户端错误
400：请求有误
401：用户未认证，请求失败
403：用户无权限访问资源，请求失败
404：资源不存在
429：访问太频繁，被限制访问
服务端错误
500：服务器错误
2.3.2 提供资源详情
所有的 200 和 201 响应，都应该返回对应的资源数据，例如：
$ curl -X POST
https://example.com/v1/apps/

HTTP/1.1 201 Created
Content-Type: application/json;charset=utf-8
…
{
“created_at”: “2020-01-01T12:00:00Z”,
“id”: 782912,
“name”: “appname”,
“updated_at”: “2020-01-01T12:00:00Z”
}
2.3.3 用 ISO8601 进行格式化时间
所有返回的时间，都必须使用 “iso-8601” 格式化，例如：“2013-01-29T12:34:56.000000Z”。
2.3.4 外键关系使用嵌套对象
需要序列化外键关联对象时，使用嵌套对象，例如：
{
“name”: “a great book name”,
“owner”: {
“id”: “9d0241a9…”,
“name”: “Ruby”,
“email”: “ruby@example.com”
},
…
}
2.3.5 统一的错误信息
使用状态码和错误信息，来配合表示错误。
客户端请求参数有误
HTTP/1.1 400 Bad Request

…
{
“参数字段名”: [“错误1”，“错误2”],
“email”: [“不合法的邮箱”],
…
}
应用业务逻辑错误
HTTP/1.1 402 Request Failed

…
{
“errors”: [
{“code”: “resource_protected”, “message”: “此资源被其他资源依赖，无法删除”},
…
]
}
限流
HTTP/1.1 429 Too Many Requests

…
{
“errors”: [
{“code”: “rate_limit”, “message”: “此账号已经被限流”},
…
]
}
2.3.6 分页
所有列表类接口，都必须开启分页返回数据，例如：
HTTP 200 OK
{
“count”: 1023
“next”: “https://api.example.org/accounts/?page=5”,
“previous”: “https://api.example.org/accounts/?page=3”,
“results”: [
…
]
}

3 API 参考文档规范
3.1 OpenAPI Schema
所有 API 需要提供 OpenAPI schemas。
3.2 提供 API 用户手册
提供给客户端开发人员使用，例如使用 Markdown 格式等，除了务必包括所有的 API 接口 reference 以外，
还需提供以下概述信息：
基本的服务地址、请求方法、注意事项、约定规范、稳定及版本管理等信息
认证方法，如何获取和使用 token
一般的请求和响应的头信息
错误处理规范和错误信息格式
针对各种场景、各种不同客户端，提供详尽的使用 API 示例
3.3 提供可执行和测试 API 的 Demo Server
如有必要，需要提供专门的服务器用来演示 API 使用
3.4 稳定性和版本管理
提供 changelog 追踪和记录各个版本变更情况。
版本 ｜ 发布日期 ｜ 修订记录 ｜备注
v0.2 ｜ 2020-02-30 ｜增加 XX 功能
｜修复 YY 问题

v0.1 ｜2020-01-02 ｜XX 系统 0.1 版本发布
4 API 服务等级要求 （SLA）
4.1 响应时间要求
一次 API 调用，响应时间最长不超过 1s，而且，满足如下指标：

percentile	latency
p95	100ms
p99	200ms

4.2 可用性要求
至少 99.99％ Availability。
4.3 系统容量
对于一台 3GHz 单核 CPU、16G 内存的机器，至少达到 100 QPS。
5 API 示例
5.1 概览
5.1.1 环境
环境 地址

develop	https://develop.example.com
preview	https://preview.example.com

5.1.2 请求方法

$ curl -i https://develop.example.com/api/v1/users/ \
    -X POST \
    -d '{"name": "username"}' \
    -H 'Content-Type: application/json'

5.1.3 认证
获取用户 token, 使用 用户名和密码:

$ curl -i https://develop.example.com/api/v1/auth/token/ \
    -X POST \
    -d '{ "username": "user", "password": "pass" }' \
    -H 'Content-Type: application/json'

HTTP 200 OK
{ "token": "abcddemo", "expires": "2013-01-29T12:34:56.000000Z"}

然后使用如下方法请求：

$ curl -H 'Authorization: Token {TOKEN}' https://develop.example.com/api/v1/users

5.2 API 列表
5.2.1 组织相关
创建一个新组织
创建一个新的组织，所有者为登录用户。

Path	POST /api/v1/organizations/
Parameters	name (string) — the human readable name for the new organization. slug (string) — the unique URL slug for this organization.
Request Example	POST /api/v1/organizations/ HTTP/1.1
Request Example	Host: develop.example.com
Request Example	Authorization: Token
Request Example	Content-Type: application/json

{ “name”: “org-name”, “slug”: “org-slug” }|

6 附录
6.1 状态码说明

Status Code	Description
100	Continue
200	OK
201	Created
202	Accepted
204	NO Content
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
405	Method Not Allowed
406	Not Acceptable
409	Conflict
410	Gone
412	Precondition Failed
429	Too many requests
500	Internal Server Error
501	Not Implemented