RESTful API？What is it?

REST全称是Representational State Transfer，中文意思是表述性状态转移。不管是英文还是中文解释，恐怕一眼看上去都难得其意！
那究竟指的是什么的表述? 其实指的就是资源。任何事物，只要有被引用到的必要，它就是一个资源。要让一个资源可以被识别，需要有个唯一标识，在Web中这个唯一标识就是URI(Uniform Resource Identifier)，标识的资源可能是服务器上的一个文件，不过，也可能是一个邮件地址、新闻消息、图书、人名、Internet主机或者任何其它内容。URI既可以看成是资源的地址，也可以看成是资源的名称，它包含URL和URN。

• URL = Universal Resource Locator 统一资源定位符
  URL唯一地标识一个资源在Internet上的位置。不管用什么方法表示，只要能定位一个资源，就叫URL。
• URN = Universal Resource Name 统一资源名称
  URN它命名资源但不指定如何定位资源，比如：只告诉你一个人的姓名，不告诉你这个人在哪。

一、URL 设计

RESTful 的核心思想就是，客户端发出的数据操作指令都是"动词 + 宾语"的结构。简单来说就是URL定位资源，用HTTP动词描述操作。
比如用GET来表示读取，POST表示新建，PUT表示更新，PATCH表示更新，但通常是部分更新，DELETE表示删除。

1.宾语必须是名词

宾语就是 API 的 URL，是 HTTP 动词作用的对象。它应该是名词，不能是动词。

GET /article

2.复数 URL

没有统一的规定，但是常见的操作是当要读取一个集合要用复数形式。

GET /articles

3.避免多级 URL

当资源需要多级分类时，比较好的做法是，除了第一级，其他级别都用查询字符串表达。这种URL不仅利于扩展，语义也更加明确。

GET /articles?published=true

二、状态码

状态码表示必须明确

• 通常来说：1xx表示相关信息，2xx表示操作成功，3xx表示重定向，4xx表示客户端错误，5xx表示服务器错误。RESTful就要求将这五类按不同请求方式进行细分。

• 以GET为例

200（OK）——表示已在响应中发出
204（无内容） —— 资源有空表示
301（Moved Permanently） —— 资源的URI已被更新
303（See Other） —— 其他（如，负载均衡）
304（not modified）—— 资源未更改（缓存）
400 （bad request）—— 指代坏请求（如，参数错误）
404 （not found）—— 资源不存在
406 （not acceptable）—— 服务端不支持所需表示
500 （internal server error）—— 通用错误响应
503 （Service Unavailable）—— 服务端当前无法处理请求

三、服务器回应

1.不要返回纯本文

API 返回的数据格式，不应该是纯文本，而应该是一个 JSON 对象，因为这样才能返回标准的结构化数据。所以，服务器回应的 HTTP 头的Content-Type属性要设为application/json。
客户端请求时，也要明确告诉服务器，可以接受 JSON 格式，即请求的 HTTP 头的ACCEPT属性也要设成application/json。

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

状态码反映发生的错误，并将具体的错误信息放在数据体里面返回。在发生错误时也返回200状态码，这种做法是不恰当的。

3.提供链接

在回应中，给出相关链接，便于下一步操作。这样的话，用户只要记住一个 URL，就可以发现其他的 URL。这种方法叫做 HATEOAS。

HATEOAS(Hypermedia as the engine of application state)，超媒体即应用状态引擎。它是REST架构的主要约束。“hepermedia”表示任何包含指向图片、电影、文字等资源的链接，Web是超媒体的经典例子。HATEOAS背后的思想其实非常简单，就是响应中包含指向其它资源的链接。客户端可以利用这些链接和服务器交互。

超媒体是什么?
当你浏览Web网页时，从一个连接跳到一个页面，再从另一个连接跳到另外一个页面，就是利用了超媒体的概念：把一个个把资源链接起来。
要达到这个目的，就要求在表述格式里边加入链接来引导客户端。在《RESTful Web Services》一书中，作者把这种具有链接的特性成为连通性。
这一特性应用特别广泛，比如创建订单后通过链接引导客户端如何去付款。

————愿你在迷茫时，坚信你的珍贵，爱你所爱，行你所行，听从你心，无问西东。