API 设计检查单

From 《Web API 的设计与开发》

• URI 是否短小且容易输入
• URI 是否能让人一眼看懂
• URI 是否只有小写字母组成
• URI 是否容易修改
• URI 是否反映了服务器端的架构
• URI 规则是否统一
• 有没有使用合适的 HTTP 方法
• URI 里用到的单词所表达的意思是否和大部分 API 相同
• URI 里用到的名词是否采用了复数形式
• URI 里有没有空格符或需要编码的字符
• URI 里的单词和单词之间有没有使用连接符
• 分页的设计是否恰当
• 登陆有没有使用OAuth2.0
• 响应数据格式有没有使用JSON作为默认格式
• 是否支持通过查询参数来指定数据格式
• 是否支持不必要的JSONP
• 响应数据的内容能不能从客户端指定
• 响应数据中是否存在不必要的封装
• 响应数据的结构有没有尽量做到扁平化
• 响应数据有没有用对象来描述，而不是用数组
• 响应数据的名称所选用的单词的意思是否和大部分 API 相同
• 响应数据的名称有没有用尽可能少的单词来描述
• 响应数据的名称由多个单词连接而成时，连接方法在整个 API 里是否一致
• 响应数据的名称有没有使用奇怪的缩写形式
• 响应数据的名称的单复数形式是否和数据内容相一致
• 出错时响应数据中是否包含有助客户端剖析原因的信息
• 出错时有没有返回 HTML 数据
• 有没有返回合适的状态码
• 服务器段在维护时有没有返回 503 状态码
• 有没有返回合适的媒体类型
• 必要时能不能支持 CORS
• 有没有返回 Cache-Control、Etag、Last-Modified、Vary 等首部以便客户端采用合适的缓存策略
• 不想缓存的数据有没有添加 Cache-Control: no-cache 首部信息
• 有没有对 API 进行版本管理
• API 版本的命名有没有遵循语义化版本控制规范
• 有没有在 URI 里嵌入主版本编号，并且能够让人一目了然
• 有没有考虑 API 终止提供时的相关事项
• 有没有在文档里明确注明 API 的最低提供期限
• 有没有使用 HTTPS 来提供 API
• 有没有认真执行 JSON 转义
• 能不能识别 X-Requested-With 首部，让浏览器无法通过 SCRIPT 元素读取 JSON 数据
• 通过浏览器访问的 API 有没有使用 XSRF Token
• API 在接受参数时有没有仔细检查非法的参数（如负数等）
• 有没有做到即使请求重复发送，数据也不会多次更新
• 有没有在响应消息里添加各种增强安全性的首部
• 有没有实施访问限次或限速
• 对预想的用例来说限速的次数有没有设置得过少