REST API 设计准则
1. URI 格式设计
a) URI 设计规则
必须使用斜杆(/)分隔来表示分层关系
不要在 URI 中使用尾部的斜杆(/)
使用中划线(-)来提供可读性
不要使用下划线(_)
小写字母优先选用
不要使用扩展名
b) URI 网站设计
所有 API 使用一致的子域名
所有开发门户使用一致的子域名
c) URI 路径设计
应使用单数名词表示单个资源
应使用复数名词表示集合资源
应使用复数名词表示存储库
应使用动词或动词词组表示控制器 v. 变量可采用 ID 值来替换
不要在 URI 中使用 CRUD 名称
d) URI 查询
URI 中的查询参数可用于过滤集合或存储库
应使用查询参数来表示集合和存储库的分页信息
2. HTTP 交互设计
a) 请求方法
一定不要使用 GET 和 POST 来发送其他请求方法
一定要使用 GET 来获取资源的信息
应使用 HEAD 来获取响应头
一定要使用 PUT 来插入和更新存储资源
一定要使用 PUT 来更新可修改资源
一定要使用 POST 来创建一个新的资源
一定要使用 POST 来执行控制器
一定要使用 DELETE 来从母资源中删除一个资源
应使用 OPTIONS 来获得表示资源接口的元数据信息
b) 应答码
应使用 200(OK)来表示通用的成功
一定不要使用 200(OK)来返回错误信息
一定要使用 201(“Created”)来表示成功的资源创建
一定要使用 202(“Accepted”)来表示异步请求的成功启动
应使用 204(“No Content”)来表示响应体为空
应使用 301(“Moved Permanently”)来表示资源重定向
不应使用 302(“Found”)
应使用 303(“See Other”)来表示参考其他的 URI
应使用 304(“Not Modified”)来节约流量
应使用 307(“Temporary Redirect”)来表示需要重新提交请求到新的 URI
可使用 400(“Bad Request”)来表示一般错误
一定要使用 401(“Unauthorized”)来表示用户身份认证失败
应使用 403(“Forbidden”)来表示用户无权访问
一定要使用 404(“Not Found”)来表示 URI 所指定的资源不存在
一定要使用 405(“Method Not Allowed”)来表示 HTTP 的方法不支持
一定要使用 406(“Not Acceptable”)来表示请求的媒介类型不可提供
应使用 409(“Conflict”)来表示资源状态冲突
应使用 412(“Precondition Failed”)来表示支持有条件操作
一定要使用 415(“Unsupported Media Type”)来表示提交的文档类型不支持
应使用 500(“Internal Server Error”)来表示 API 功能不正常
3. 元数据设计
a) HTTP 头
一定要使用 Content-Type
应使用 Content-Length
应在响应中使用 Last-Modified iv. 应在响应中使用 ETag
存储库必须支持有条件的 PUT 请求
必须要用 Location 来表示新资源的 URI
应使用 Cache-Control、Expires 和 Data 响应头来鼓励缓存
可使用 Cache-Control、Expires 和 Pragma 来不鼓励缓存
应使用 max-age，不应使用 no-cache
应使用 200(“OK”)响应过期的缓存
可使用 3xx 和 4xx 来选择性响应过期的缓存请求
一定不要使用个性化的 HTTP 头来修改 HTTP 的方法
b) 媒介类型
应使用应用相关的媒介类型
应支持媒介类型的协商功能（当多种媒介类型可用时）
可支持使用查询参数来选择媒介类型
4. 内容表示
a) 消息体
应支持使用 JSON 来表示资源
JSON 格式必须正确
可选择性地支持 XML 和其他格式
一定不要使用额外的内容包头
b) 超媒体表示
应使用标准的格式表示链接
应使用标准的格式表示链接关系
应使用标准的格式表示广告链接
响应消息体中应使用 self 链接
广告“入口“URI 的数量最小化
应使用链接来表示资源可用的与状态相关的动作，如剪贴、复制等
c) 媒介类型
媒介类型应该保持一致
媒介类型的 schema 应保持一致
d) 错误
表示错误的格式应保持一致
表示错误响应的格式应保持一致
相同错误条件下的错误类型应保持一致
5. 客户端相关问题
a) 版本
新 URI 应该用于新概念（概念相同就不要修改，所以版本主要在 URI 中）
Schema 应该用于管理表示方式的版本
实体标签 ETag 应该用于管理表示状态的版本
b) 安全
可使用 OAuth 来保护资源
可使用 API 管理解决方案来保护资源
c) 部分响应内容
应通过 URI 的查询组件来支持部分响应，如 fields 参数
d) Javascript 客户端
应支持通过 JSONP 方式进行多源读访问
应支持 CORS，提供多源读写访问（Access-Control-Allow-Origin）
文章评论