WebAPI的设计规范


原文链接: WebAPI的设计规范

URI是否短小且容易输人

URI是否能让人一眼看懂

URI是否只有小写字母组成

URI是否容易修改

URI是否反映了服务器端的架构

URI规则是否统一

有没有使用合适的HTTP方法

URI里用到的单词所表示的意思是否和大部分API相同

URI里用到的名词是否采用了复数形式

URI里有没有空格符及需要编码的字符

URI里的单词和单词之间有没有使用连接符

分页的设计是否恰当

登录有没有使用 Oauth2.0

响应数据格式有没有使用JSON作为默认格式

是否支持通过查询参数来指定数据格式

是否支持不必要的 JSONP

响应数据的内容能不能从客户端指定

响应数据中是否存在不必要的封装

响应数据的结构有没有尽量做到扁平化

响应数据有没有用对象来描述,而不是用数组

响应数据的名称所选用的单词的意思是否和大部分API相同

响应数据的名称有没有用尽可能少的单词来描述

响应数据的名称由多个单词连接而成时,连接方法在整个AP1里是否一致

响应数据的名称有没有使用奇怪的缩写形式

响应数据的名称的单复数形式是否和数据内容相一致

出错时响应数据中是否包含有助于客户端剖析原因的信息

出错时有没有返回HTML数据

有没有返回合适的状态码

服务器端在维护时有没有返回503状态码

有没有返回合适的媒体类型

必要时能不能支持CORS

有没有返回 Cache- Contro1、ETag、Last- Modified、Vary等首部以便客户端采用合适的缓存策略

不想缓存的数据有没有添加 Cache- Contro1:no- cache首部信息

有没有对API进行版本管理

API版本的命名有没有遵循语义化版本控制规范

有没有在URI里嵌入主版本编号,并且能够让人一目了然

有没有考虑API终止提供时的相关事项

有没有在文档里明确注明API的最低提供期限

有没有使用 HTTPS来提供API

有没有认真执行JSON转义

能不能识别x- Requested-With首部,让浏览器无法通过 SCRIPT元素读取JSON数据

通过浏览器访问的API有没有使用 XSRF token

API在接收参数时有没有仔细检查非法的参数(负数等)

有没有做到即使请求重复发送,数据也不会多次更新

有没有在响应消息里添加各种增强安全性的首部

有没有实施访问限速

对预想的用例来说限速的次数有没有设置得过少

作者:君惜丶

`