restful接口设计规范总结

这篇 文章主要是借鉴他人，可是本身很想总结出一套规范，以供向我这样的新手使用，用来规范代码，若是有什么好的提议，请不吝赐教，本篇文章长期更新！

1、重要概念：

REST,即Representational State Transfer的缩写。我对这个词组的翻译是"表现层状态转化"。

Resource（资源） ：对象的单个实例。 例如，一只动物。它能够是一段文本、一张图片、一首歌曲、一种服务，总之就是一个具体的实在。你能够用一个URI（统一资源定位符）指向它，每种资源对应一个特定的URI。要获取这个资源，访问它的URI就能够，所以URI就成了每个资源的地址或独一无二的识别符。

集合：对象的集合。 例如，动物。

第三方：使用咱们接口的开发者

表现层（Representation）

"资源"是一种信息实体，它能够有多种外在表现形式。咱们把"资源"具体呈现出来的形式，叫作它的"表现层"（Representation）。

状态转化（State Transfer）

访问一个网站，就表明了客户端和服务器的一个互动过程。在这个过程当中，势必涉及到数据和状态的变化。互联网通讯协议HTTP协议，是一个无状态协议。这意味着，全部的状态都保存在服务器端。所以，若是客户端想要操做服务器，必须经过某种手段，让服务器端发生"状态转化"（State Transfer）。而这种转化是创建在表现层之上的，因此就是"表现层状态转化"。

客户端用到的手段，只能是HTTP协议。具体来讲，就是HTTP协议里面，四个表示操做方式的动词：GET、POST、PUT、DELETE。它们分别对应四种基本操做：GET用来获取资源，POST用来新建资源（也能够用于更新资源），PUT用来更新资源，DELETE用来删除资源。

好比，文本能够用txt格式表现，也能够用HTML格式、XML格式、JSON格式表现，甚至能够采用二进制格式；图片能够用JPG格式表现，也能够用PNG格式表现。

URI只表明资源的实体，不表明它的形式。严格地说，有些网址最后的".html"后缀名是没必要要的，由于这个后缀名表示格式，属于"表现层"范畴，而URI应该只表明"资源"的位置。它的具体表现形式，应该在HTTP请求的头信息中用Accept和Content-Type字段指定，这两个字段才是对"表现层"的描述。

综合上面的解释，咱们总结一下什么是RESTful架构：

　（1）每个URI表明一种资源；

　（2）客户端和服务器之间，传递这种资源的某种表现层；

　（3）客户端经过四个HTTP动词，对服务器端资源进行操做，实现"表现层状态转化"。

2、REST接口规范

一、动做

GET （SELECT）：从服务器检索特定资源，或资源列表。POST （CREATE）：在服务器上建立一个新的资源。PUT （UPDATE）：更新服务器上的资源，提供整个资源。PATCH （UPDATE）：更新服务器上的资源，仅提供更改的属性。DELETE （DELETE）：从服务器删除资源。

首先是四个半种动做：post、delete、put/patch、get由于put/patch只能算做一类，因此将patch归为半个。

另外还有有两个较少知名的HTTP动词：HEAD - 检索有关资源的元数据，例如数据的哈希或上次更新时间。OPTIONS - 检索关于客户端被容许对资源作什么的信息。

二、路径（接口命名）

路径又称"终点"（endpoint），表示API的具体网址。

在RESTful架构中，每一个网址表明一种资源（resource），因此网址中不能有动词，只能有名词，并且所用的名词每每与数据库的表格名对应。通常来讲，数据库中的表都是同种记录的"集合"（collection），因此API中的名词也应该使用复数。

举例来讲，有一个API提供动物园（zoo）的信息，还包括各类动物和雇员的信息，则它的路径应该设计成下面这样。

接口尽可能使用名词，禁止使用动词，下面是一些例子。

GET         /zoos：列出全部动物园
POST        /zoos：新建一个动物园
GET         /zoos/ID：获取某个指定动物园的信息
PUT         /zoos/ID：更新某个指定动物园的信息（提供该动物园的所有信息）
PATCH       /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）
DELETE      /zoos/ID：删除某个动物园
GET         /zoos/ID/animals：列出某个指定动物园的全部动物
DELETE      /zoos/ID/animals/ID：删除某个指定动物园的指定动物复制代码

反例：

/getAllCars
/createNewCar
/deleteAllRedCars复制代码

再好比，某个URI是/posts/show/1，其中show是动词，这个URI就设计错了，正确的写法应该是/posts/1，而后用GET方法表示show。

若是某些动做是HTTP动词表示不了的，你就应该把动做作成一种资源。好比网上汇款，从帐户1向帐户2汇款500元，错误的URI是：

　　POST /accounts/1/transfer/500/to/2

正确的写法是把动词transfer改为名词transaction，资源不能是动词，可是能够是一种服务：

　　POST /transaction HTTP/1.1

　　Host: 127.0.0.1

　　from=1&to=2&amount=500.00

理清资源的层次结构，好比业务针对的范围是学校，那么学校会是一级资源(/school)，老师(/school/teachers)，学生(/school/students)就是二级资源。

三、版本（Versioning）

应该将API的版本号放入URL。如：

https://api.example.com/v1/复制代码

另外一种作法是，将版本号放在HTTP头信息中，但不如放入URL方便和直观。Github采用这种作法。

四、过滤信息（Filtering）

若是记录数量不少，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。下面是一些常见的参数。

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page_number=2&page_size=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪一个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件
参数的设计容许存在冗余，即容许API路径和URL参数偶尔有重复。好比，
GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。复制代码

五、状态码（Status Codes）

状态码范围

1xx 信息，请求收到，继续处理。范围保留用于底层HTTP的东西，你极可能永远也用不到。
2xx 成功，行为被成功地接受、理解和采纳
3xx 重定向，为了完成请求，必须进一步执行的动做
4xx 客户端错误，请求包含语法错误或者请求没法实现。范围保留用于响应客户端作出的错误，例如。他们提供不良数据或要求不存在的东西。这些请求应该是幂等的，而不是更改服务器的状态。
5xx 范围的状态码是保留给服务器端错误用的。这些错误经常是从底层的函数抛出来的，甚至
开发人员也一般无法处理，发送这类状态码的目的以确保客户端得到某种响应。
当收到5xx响应时，客户端不可能知道服务器的状态，因此这类状态码是要尽量的避免。复制代码

服务器向用户返回的状态码和提示信息，常见的有如下一些（方括号中是该状态码对应的HTTP动词）。

200 OK - [GET]：服务器成功返回用户请求的数据，该操做是幂等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]：用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操做，该操做是幂等的。
401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
403 Forbidden - [*] 表示用户获得受权（与401错误相对），可是访问是被禁止的。
404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操做，该操做是幂等的。
406 Not Acceptable - [GET]：用户请求的格式不可得（好比用户请求JSON格式，可是只有XML格式）。
410 Gone -[GET]：用户请求的资源被永久删除，且不会再获得的。
422 Unprocesable entity - [POST/PUT/PATCH] 当建立一个对象时，发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将没法判断发出的请求是否成功。
502 网关错误
503 Service Unavailable
504 网关超时复制代码

参考资料：

RESTful API 设计指南--阮一峰：http://www.ruanyifeng.com/blog/2014/05/restful_api.html