设计优美的 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 头部字段

让用户决定响应的内容

• GraphQL

通过状态码表示错误信息

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