RESTful API 接口设计规范.pdfVIP

RESTful API 设计规范 该仓库整理了⽬前⽐较流⾏的 RESTful api 设计规范，为了⽅便讨论规范带来的问题及争议，现把该 ⽂档托管于 Github ，欢迎⼤家补充！！ Table of Contents RESTful API 设计规范 关于「能愿动词」的使⽤ Protocol API Root URL Versioning 在 URL 中嵌⼊版本编号 通过媒体类型来指定版本信息 Endpoints HTTP 动词 Filtering Authentication Response 200 ok 201 Created 202 Accepted 204 No Content 3xx 重定向 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 405 Method Not Allowd 406 Not Acceptable 408 Request Timeout 409 Gonfilct 410 Gone 413 Request Entity Too Large 414 Request-URI Too Long 415 Unsupported Media Type 429 Too Many Request 500 Internal Server Error 503 Service Unavailable 版权声明 建议参考 LICENSE 关于「能愿动词」的使⽤ 为了避免歧义，⽂档⼤量使⽤了「能愿动词」，对应的解释如下： 必须 (MUST) ：绝对，严格遵循，请照做，⽆条件遵守； ⼀定不可 (MUST NOT) ：禁令，严令禁⽌； 应该 (SHOULD) ：强烈建议这样做，但是不强求； 不该 (SHOULD NOT) ：强烈不建议这样做，但是不强求； 可以 (MAY) 和 可选 (OPTIONAL) ：选择性⾼⼀点，在这个⽂档内，此词语使⽤较少； 参⻅：RFC 2119 Protocol 客户端在通过 API 与后端服务通信的过程中，应该 使⽤ HTTPS 协议。 API Root URL API 的根⼊⼝点应尽可能保持⾜够简单，这⾥有两个常⻅的 URL 根例⼦： /* /api/* 如果你的应⽤很庞⼤或者你预计它将会变的很庞⼤，那 应该 将 API 放到⼦域下 （ ）。这种做法可以保持某些规模化上的灵活性。 Versioning 所有的 API 必须保持向后兼容，你 必须 在引⼊新版本 API 的同时确保旧版本 API 仍然可⽤。所以 应该 为其提供版本⽀持。 ⽬前⽐较常⻅的两种版本号形式： 在 URL 中嵌⼊版本编号 /v1/* 这种做法是版本号直观、易于调试；另⼀种做法是，将版本号放在 HTTP Header 头中： 通过媒体类型来指定版本信息 Accept: application/.v1+json 其中 vnd 表示 Standards Tree 标准树类型，有三个不同的树: x ，prs 和 vnd 。你使⽤的标准树需 要取决于你开发的项⽬ 未注册的树（x ）主要表示本地和私有环境 私有树（prs ）主要表示没有商业发布的项⽬ 供应商树（vnd ）主要表示公开发布的项⽬ 后⾯⼏个参数依次为应⽤名称（⼀般为应⽤域名）、版本号、期望的返回格式。 ⾄于具体把版本号放在什么地⽅，这个问题⼀直存在很⼤的争议，但由于我们⼤多数时间都在使⽤ Laravel 开发，应该 使⽤dingo/api 来快速构建应⽤，它采⽤第⼆种⽅式来管理 API 版本，并且已 集成了标准的 HTTP Response 。 Endpoints 端点就是指向特定资源或资源集合的 URL 。在端点的设计中，你 必须 遵守下列约定： URL 的命名 必须 全部⼩写 URL 中资源（r