在服务器端，应用程序状态和功能可以分为各种资源。资源是一个有趣的概念实体，它向客户端公开。资源的例子有：应用程序对象、数据库记录、算法等等。

每个资源都使用 URI (Universal Resource Identifier) 得到一个惟一的地址。

所有资源都共享统一的界面，以便在客户端和服务器之间传输状态。使用的是标准的 HTTP 方法，比如 GET、PUT、POST 和 DELETE。

Hypermedia 是应用程序状态的引擎，资源表示通过超链接互联。

另一个重要的 REST 原则是分层系统，这表示组件无法了解它与之交互的中间层以外的组件。通过将系统知识限制在单个层，可以限制整个系统的复杂性，促进了底层的独立性。

REST 描述了一个架构样式的互联系统（如 Web 应用程序）。REST 约束条件作为一个整体应用时，将生成一个简单、可扩展、有效、安全、可靠的架构。由于它简便、轻量级以及通过 HTTP 直接传输数据的特性，RESTful Web 服务成为基于 SOAP 服务的一个最有前途的替代方案。用于 web 服务和动态 Web 应用程序的多层架构可以实现可重用性、简单性、可扩展性和组件可响应性的清晰分离。开发人员可以轻松使用 Ajax 和 RESTful Web 服务一起创建丰富的界面。

REST最早是由Roy Fielding博士发表的论文中提到的，他也曾参与设计了HTTP协议。论文地址：http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

定义：简单来说REST是一种系统架构设计风格（而非标准），一种分布式系统的应用层解决方案。REST 指的是一组架构约束条件和原则。

满足这些约束条件和原则的应用程序或设计就是 RESTful。

为什么使用RESTful API ？

RESTful 给我的最大感觉就是规范、易懂和优雅，一个结构清晰、易于理解的 API 完全可以省去许多无意义的沟通和文档。并且 RESTful 现在越来越流行，也有越来越多优秀的周边工具（例如文档工具 Swagger）。

采用RESTful来设计API主要有以下好处：

一、表现力更强，更易于理解

二、RESRful是无状态，所以不管前端是何种设备何种状态都可以无差别的请求资源

RESTful API 有哪些内容？

一.使用METHOD (POST,DELETE,GET,PUT) 等动词表示増删查改四种操作.

二.使用URI(通常是其子集URL)来表示对象或资源.

三.使用queryString表示查询输入

四.使用body表示更新和保存的状态输入

五.使用HEAD进行扩展

怎么使用RESTful API？

一、每个资源使用2个URL，网址中只能有名词

二、对于资源的操作类型由HTTP动词来表示

三、统一的返回结果

四、返回正确的状态码

五、允许通过HTTP内容协商，建议格式预定义为JSON

六、对可选发杂的参数，使用查询字符串（？）

七、返回有用的错误信息(message)

八、非资源请求用动词，这看起似乎和1中的说法有矛盾，但这里指的是非资源，而不是资源

RESTful架构有哪些优点

一.前后端分离，减少流量

二.安全问题集中在接口上，由于接受json格式，防止了注入型等安全问题

三.前端无关化，后端只负责数据处理，前端表现方式可以是任何前端语言（android，ios,html5）

四.前端和后端人员更加专注于各自开发，只需接口文档便可完成前后端交互，无需过多相互了解

五.服务器性能优化：由于前端是静态页面，通过nginx便可获取，服务器主要压力放在了接口上

RESTful API 最佳实践

一、URL 设计

1.1 动词 + 宾语

RESTful 的核心思想就是，客户端发出的数据操作指令都是"动词 + 宾语"的结构。比如，GET /articles这个命令，GET是动词，/articles是宾语。

动词通常就是五种 HTTP 方法，对应 CRUD 操作。

• GET：读取（Read）
• POST：新建（Create）
• PUT：更新（Update）
• PATCH：更新（Update），通常是部分更新
• DELETE：删除（Delete）

根据 HTTP 规范，动词一律大写。

1.2 动词的覆盖

有些客户端只能使用GET和POST这两种方法。服务器必须接受POST模拟其他三个方法（PUT、PATCH、DELETE）。

这时，客户端发出的 HTTP 请求，要加上X-HTTP-Method-Override属性，告诉服务器应该使用哪一个动词，覆盖POST方法。

POST /api/Person/4 HTTP/1.1  
X-HTTP-Method-Override: PUT

上面代码中，X-HTTP-Method-Override指定本次请求的方法是PUT，而不是POST。

1.3 宾语必须是名词

宾语就是 API 的 URL，是 HTTP 动词作用的对象。它应该是名词，不能是动词。比如，/articles这个 URL 就是正确的，而下面的 URL 不是名词，所以都是错误的。

• /getAllCars
• /createNewCar
• /deleteAllRedCars

1.4 复数 URL

既然 URL 是名词，那么应该使用复数，还是单数？

这没有统一的规定，但是常见的操作是读取一个集合，比如GET /articles（读取所有文章），这里明显应该是复数。

为了统一起见，建议都使用复数 URL，比如GET /articles/2要好于GET /article/2。

1.5 避免多级 URL

常见的情况是，资源需要多级分类，因此很容易写出多级的 URL，比如获取某个作者的某一类文章。

GET /authors/12/categories/2

这种 URL 不利于扩展，语义也不明确，往往要想一会，才能明白含义。

更好的做法是，除了第一级，其他级别都用查询字符串表达。

GET /authors/12?categories=2

下面是另一个例子，查询已发布的文章。你可能会设计成下面的 URL。

GET /articles/published

查询字符串的写法明显更好。

GET /articles?published=true

二、状态码

2.1 状态码必须精确

客户端的每一次请求，服务器都必须给出回应。回应包括 HTTP 状态码和数据两部分。

HTTP 状态码就是一个三位数，分成五个类别。

• 1xx：相关信息
• 2xx：操作成功
• 3xx：重定向
• 4xx：客户端错误
• 5xx：服务器错误

这五大类总共包含100多种状态码，覆盖了绝大部分可能遇到的情况。每一种状态码都有标准的（或者约定的）解释，客户端只需查看状态码，就可以判断出发生了什么情况，所以服务器应该返回尽可能精确的状态码。

API 不需要1xx状态码，下面介绍其他四类状态码的精确含义。

2.2 2xx 状态码

200状态码表示操作成功，但是不同的方法可以返回更精确的状态码。

• GET: 200 OK
• POST: 201 Created
• PUT: 200 OK
• PATCH: 200 OK
• DELETE: 204 No Content

上面代码中，POST返回201状态码，表示生成了新的资源；DELETE返回204状态码，表示资源已经不存在。

此外，202 Accepted状态码表示服务器已经收到请求，但还未进行处理，会在未来再处理，通常用于异步操作。下面是一个例子。

HTTP/1.1 202 Accepted

{
  "task": {
    "href": "/api/company/job-management/jobs/2130040",
    "id": "2130040"
  }
}

2.3 3xx 状态码

API 用不到301状态码（永久重定向）和302状态码（暂时重定向，307也是这个含义），因为它们可以由应用级别返回，浏览器会直接跳转，API 级别可以不考虑这两种情况。

API 用到的3xx状态码，主要是303 See Other，表示参考另一个 URL。它与302和307的含义一样，也是"暂时重定向"，区别在于302和307用于GET请求，而303用于POST、PUT和DELETE请求。收到303以后，浏览器不会自动跳转，而会让用户自己决定下一步怎么办。下面是一个例子。

HTTP/1.1 303 See Other
Location: /api/orders/12345

2.4 4xx 状态码

4xx状态码表示客户端错误，主要有下面几种。

400 Bad Request：服务器不理解客户端的请求，未做任何处理。

401 Unauthorized：用户未提供身份验证凭据，或者没有通过身份验证。

403 Forbidden：用户通过了身份验证，但是不具有访问资源所需的权限。

404 Not Found：所请求的资源不存在，或不可用。

405 Method Not Allowed：用户已经通过身份验证，但是所用的 HTTP 方法不在他的权限之内。

410 Gone：所请求的资源已从这个地址转移，不再可用。

415 Unsupported Media Type：客户端要求的返回格式不支持。比如，API 只能返回 JSON 格式，但是客户端要求返回 XML 格式。

422 Unprocessable Entity ：客户端上传的附件无法处理，导致请求失败。

429 Too Many Requests：客户端的请求次数超过限额。

2.5 5xx 状态码

5xx状态码表示服务端错误。一般来说，API 不会向用户透露服务器的详细信息，所以只要两个状态码就够了。

500 Internal Server Error：客户端请求有效，服务器处理时发生了意外。

503 Service Unavailable：服务器无法处理请求，一般用于网站维护状态。

三、服务器回应

3.1 不要返回纯本文

API 返回的数据格式，不应该是纯文本，而应该是一个 JSON 对象，因为这样才能返回标准的结构化数据。所以，服务器回应的 HTTP 头的Content-Type属性要设为application/json。

客户端请求时，也要明确告诉服务器，可以接受 JSON 格式，即请求的 HTTP 头的ACCEPT属性也要设成application/json。下面是一个例子。

GET /orders/2 HTTP/1.1 
Accept: application/json

3.2 发生错误时，不要返回 200 状态码

有一种不恰当的做法是，即使发生错误，也返回200状态码，把错误信息放在数据体里面，就像下面这样。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "failure",
  "data": {
    "error": "Expected at least two items in list."
  }
}

上面代码中，解析数据体以后，才能得知操作失败。

这张做法实际上取消了状态码，这是完全不可取的。正确的做法是，状态码反映发生的错误，具体的错误信息放在数据体里面返回。下面是一个例子。

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Invalid payoad.",
  "detail": {
     "surname": "This field is required."
  }
}

3.3 提供链接

API 的使用者未必知道，URL 是怎么设计的。一个解决方法就是，在回应中，给出相关链接，便于下一步操作。这样的话，用户只要记住一个 URL，就可以发现其他的 URL。这种方法叫做 HATEOAS。

举例来说，GitHub 的 API 都在 api.github.com 这个域名。访问它，就可以得到其他 URL。

{
  ...
  "feeds_url": "https://api.github.com/feeds",
  "followers_url": "https://api.github.com/user/followers",
  "following_url": "https://api.github.com/user/following{/target}",
  "gists_url": "https://api.github.com/gists{/gist_id}",
  "hub_url": "https://api.github.com/hub",
  ...
}

上面的回应中，挑一个 URL 访问，又可以得到别的 URL。对于用户来说，不需要记住 URL 设计，只要从 api.github.com 一步步查找就可以了。

HATEOAS 的格式没有统一规定，上面例子中，GitHub 将它们与其他属性放在一起。更好的做法应该是，将相关链接与其他属性分开。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "In progress",
   "links": {[
    { "rel":"cancel", "method": "delete", "href":"/api/status/12345" } ,
    { "rel":"edit", "method": "put", "href":"/api/status/12345" }
  ]}
}

Token 和 Sign

API 需要设计成无状态，所以客户端在每次请求时都需要提供有效的 Token 和 Sign，在我看来它们的用途分别是：

• Token 用于证明请求所属的用户，一般都是服务端在登录后随机生成一段字符串（UUID）和登录用户进行绑定，再将其返回给客户端。Token 的状态保持一般有两种方式实现：一种是在用户每次操作都会延长或重置 TOKEN 的生存时间（类似于缓存的机制），另一种是 Token 的生存时间固定不变，但是同时返回一个刷新用的 Token，当 Token 过期时可以将其刷新而不是重新登录。
• Sign 用于证明该次请求合理，所以一般客户端会把请求参数拼接后并加密作为 Sign 传给服务端，这样即使被抓包了，对方只修改参数而无法生成对应的 Sign 也会被服务端识破。当然也可以将时间戳、请求地址和 Token 也混入 Sign，这样 Sign 也拥有了所属人、时效性和目的地。

统计性参数

我不太清楚这类参数具体该被称为什么，总之就是用户的各种隐私【误。类似于经纬度、手机系统、型号、IMEI、网络状态、客户端版本、渠道等，这些参数会经常收集然后用作运营、统计等平台，但是在大部分情况下他们是与业务无关的。这类参数变化不频繁的可以在登录时提交，变化比较频繁的可以用轮训或是在其他请求中附加提交。

业务参数

在 RESTful 的标准中，PUT 和 PATCH 都可以用于修改操作，它们的区别是 PUT 需要提交整个对象，而 PATCH 只需要提交修改的信息。但是在我看来实际应用中不需要这么麻烦，所以我一律使用 PUT，并且只提交修改的信息。

另一个问题是在 POST 创建对象时，究竟该用表单提交更好些还是用 JSON 提交更好些。其实两者都可以，在我看来它们唯一的区别是 JSON 可以比较方便的表示更为复杂的结构（有嵌套对象）。另外无论使用哪种，请保持统一，不要两者混用。

还有一个建议是最好将过滤、分页和排序的相关信息全权交给客户端，包括过滤条件、页数或是游标、每页的数量、排序方式、升降序等，这样可以使 API 更加灵活。但是对于过滤条件、排序方式等，不需要支持所有方式，只需要支持目前用得上的和以后可能会用上的方式即可，并通过字符串枚举解析，这样可见性要更好些。例如：

搜索，客户端只提供关键词，具体搜索的字段，和搜索方式（前缀、全文、精确）由服务端决定：

/users/?query=ScienJus

过滤，只需要对已有的情况进行支持：

/users/?gender=1

对于某些特定且复杂的业务逻辑，不要试图让客户端用复杂的查询参数表示，而是在 URL 使用别名：

/users/recommend

分页：

/users/?offset=10&limit=10

/articles/?cursor=2015-01-01 15:20:30&limit=10

/users/?page=2&pre_page=20

排序，只需要对已有的情况进行支持：

/articles/sort=-create_date

PS：我很喜欢这种在字段名前面加-表示降序排列的方式。

返回数据

JSON 比 XML 可视化更好，也更加节约流量，所以尽量不要使用 XML。

创建和修改操作成功后，需要返回该资源的全部信息。

返回数据不要和客户端界面强耦合，不要在设计 API 时就考虑少查询一张关联表或是少查询 / 返回几个字段能带来多大的性能提升。并且一定要以资源为单位，即使客户端一个页面需要展示多个资源，也不要在一个接口中全部返回，而是让客户端分别请求多个接口。

最好将返回数据进行加密和压缩，尤其是压缩在移动应用中还是比较重要的。

分页

在 APP 后端分页设计 中提到过，分页布局一般分为两种，一种是在 Web 端比较常见的有底部分页栏的电梯式分页，另一种是在 APP 中比较常见的上拉加载更多的流式分页。这两种分页的 API 到底该如何设计呢？

电梯式分页需要提供page（页数）和pre_page（每页的数量）。例如：

/users/?page=2&pre_page=20

而服务端则需要额外返回total_count（总记录数），以及可选的当前页数、每页的数量（这两个与客户端提交的相同）、总页数、是否有下一页、是否有上一页（这三个都可以通过总记录数计算出）。例如：

{
    "pagination": {
       "previous": 1,
       "next": 3,
       "current": 2,
       "per_page": 20,
       "total": 200,
       "pages": 10
    },
    "data": {}
}

流式布局也完全可以使用这种方式，并且不需要查询总记录数（好处是减少一次数据库操作，坏处时客户端需要多请求一次才能判断是否到最后一页）。但是会出现数据重复和缺失的情况，所以更推荐使用游标分页。

游标分页需要提供cursor(下一页的起点游标) 和limit(数量) 参数。例如：

/articles/?cursor=2015-01-01 15:20:30&limit=10

如果文章列表默认是以创建时间为倒序排列的，那么cursor就是当前列表最后一条的创建时间（第一页为当前时间）。

服务端需要返回的数据也很简单，只需要以此游标为起点的总记录数和下一个起点游标就可以了。例如：

{
    "pagination": {
       "next": "2015-01-01 12:20:30",
       "limit": 10,
       "total": 100,
    },
    "data": {}
}

如果total小于limit，就说明已经没有数据了。

流式布局的分页 API 还有一种情况很常见，就是下拉刷新的增量更新。它的业务逻辑正好和游标分页相反，但是参数基本一样：

/articles/?cursor=2015-01-01 15:20:30&limit=20

返回数据有两种可能，一种是增量更新的数据小于指定的数量，就直接将全部数据返回（这个数量可以设置的相对大一些），客户端会将这些增量更新的数据添加在已有列表的顶部。但是如果增量更新的数据要大于指定的数量，就会只返回最新的 n 条数据作为第一页，这时候客户端需要清空之前的列表。例如：

{
    "pagination": {
       "limit": 20,
       "total": 100,
    },
    "data": {}
}

如果total大于limit，说明增量的数据太多所以只返回了第一页，需要清空旧的列表。