restful Api规范

简介

写接口的开发人员一定不会对它感到陌生，概念啥的就简单介绍一下，主要梳理一下 resful 设计关键内容。resful 全称 Representational State Transfer 是一种软件设计风格。其设计的目的是为了给开发者提供一种设计理念，统一接口开发的规范。

命名规范

在 Restful 架构中，所有一切都是资源。每一个 URL 都代表着一种资源，而且大部分情况下都是名词的复数，尽量不要出现动词。
eg:

GET /issues                                      列出所有的 issue
GET /orgs/:org/issues                            列出某个项目的 issue
GET /repos/:owner/:repo/issues/:number           获取某个项目的某个 issue
POST /repos/:owner/:repo/issues                  为某个项目创建 issue
PATCH /repos/:owner/:repo/issues/:number         修改某个 issue
PUT /repos/:owner/:repo/issues/:number/lock      锁住某个 issue
DELETE /repos/:owner/:repo/issues/:number/lock   接收某个 issue

例子中的冒号表示的是变量

HTTP动词描述操作

Http 中有许多动词可以来描述用户不同的操作，常见的动词及含义如下表所示：

动词	描述
GET	获取资源，单个或多个
POST	创建资源
PUT	更新资源，客户端提供完整的资源数据
PATCH	更新资源，客户端提供部分资源数据
DELETE	删除资源

资源过滤

接口需要能够提供合理的参数供客户端过滤资源，eg:

?state=closed: 不同状态的资源。
?page=2&per_page=100：访问第几页数据，每页多少条。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。

响应状态码

正确的使用状态码，可以使响应数据更加具备可读性，eg:

• 200 OK 对成功的 GET,PUT,PATCH,DELETE 操作进行响应。
• 201 Created 对创建新资源的 POST 操作进行响应。
• 202 Accepted 服务器接收了请求，但是还未处理，响应中应该包含相应的指示信息，告诉客户端应该去哪里查询本次请求的信息。
• 204 No Content 成功处理请求，但返回的响应体中不含实体的主体部分。
• 301 Permanently Moved 永久性重定向，代表之前请求的资源地址已经发生了变化。
• 302 Temporarily Moved 临时重定向。
• 304 Not Modified Http 缓存header 生效时使用。
• 400 Bad Request 请求异常，比如请求中的 body 无法解析。
• 401 Unauthorized 没有进行认证或者认证非法。
• 403 Forbidden 服务器已经理解请求，但是拒绝执行它。
• 404 Not Found 请求一个不存在的资源。
• 405 Method Not Allowed 所请求的 Http 方法不允许当前认证用户访问。
• 410 Gone 表示当前请求的资源不再可用。当调用老版本的 API 时很有用。
• 415 Unsupported Media Type 请求中的内容类型是错误的。
• 422 Unprocessable Entity 用来校验错误。
• 429 Too Many Requests 由于请求频次达到上限而被拒绝访问。
• 500 Internal Server Error 服务器内部错误
• 503 Service unavailable 服务器处于宕机状态