设计优美的 Web API
易于使用、便于更改、健壮性好、不怕公开
REST 的两层含义
- 指符合 Fielding 的 REST 架构风格的 Web 服务系统
- 指使用符合 RPC 风格的 XML 或 JSON + HTTP 接口的系统(不使用 SOAP)
端点的基本设计
- 短小便于输入的 URI-
- 人可以读懂的 URI
- 没有大小写混用的 URI
- 修改方便的 URI
- 不暴露服务端架构的 URI
- 规则统一的 URI
HTTP 方法和端点
- GET 获取资源
- POST 新增资源
- PUT 更新已有资源
- DELETE 删除资源
- PATCH 更新部分资源
查询参数和路径的使用区别
- 表示唯一资源时，放在路径中
- 当参数可以忽略时，放在查询参数中
RESTful 的设计级别
- 使用 HTTP
- 引入资源的概念
- 引入 HTTP 动词
- 引入 HATEOAS
如何指定数据格式
- 查询参数：url?format=xml
- 扩展名：/url.json
- Accept 头部字段
让用户决定响应的内容
通过状态码表示错误信息
1xx：消息
2xx：成功
3xx：重定向
4xx：客户端原因造成的错误
5xx：服务端原因造成的错误
缓存与 HTTP 协议规范
RFC7234：过期模型/验证模型
过期模型：Cache-Control/Expires
验证模型：Last-Modified/ETag
Vary 首部：指定缓存单位
Conent-Type/Accept：指定媒体类型
API 版本控制
- 在 URI 中嵌入版本号
- 在查询字符串中加入版本信息
- 通过媒体类型指定版本
API 安全问题
- 推荐使用 HTTPS
- XSS/XSRF 注入漏洞
- 返回正确的数据格式
- 使用安全相关首部
- 采用 KVS 实现访问限制
提供 API 文档
- API Blueprint
- API Console/Apigee
- 提供 SDK
