深入理解RESTful

REST是一种互联网软件架构原则，Representational State Transfer，翻译为表现层状态转化。如果一个架构符合REST原则，就称它为RESTful架构。

本文目的——设计符合RESTful 规范的API

1 看Url就知道要什么
2 看http method就知道干什么
3 看http status code就知道结果如何

参考资料

RESTful的作用与优点

制定一套符合标准，容易理解，可读性高，易于协作的API规范。

现在的web应用，我们完全可以理解为是一种软件，是一种互联网软件。这种互联网软件，有别于传统软件，采用客户端/服务端模式，建立在分布式体系上，通过互联网通信。REST架构，就是在符合架构原理的前提下，以网络为基础的应用软件的架构设计，它结构清晰、符合标准、易于理解、扩展方便，所以正得到越来越多网站的采用。
区别于传统的软件，网络通信是这种互联网软件的核心，RESTful架构所提供的RESTful　API　标准明确，可读性高，易于理解，灵活可扩展，为客户端服，务端的通信提供了良好的解决方案。
互联网公司面临多重挑战：一方面智能手机，平板电脑这些移动设备层出不穷，需要支持这些设备，即我们的web和移动端都可以调用相同的接口；另一方面无论是公司内部的数据互通（微服务间的通信）还是和外部合作（暴露接口给第三方），都需要展示相同的业务逻辑。现在越来越多公司采用的策略是，让服务端所有商业逻辑RESTful　API 的方式暴露给客户端，浏览器可以使用Ajax、HTML５等技术，通过HTTP的方式与后台直接交互，即做到前后端分离。这种开发机制有很好的扩展性，又减少了开发复杂度。

理解RESTful

URL定位资源，用HTTP动词（GET,POST,PUT,DELETE,）描述操作

图片.png

资源：操作的实体对象。REST的名称"表现层状态转化"中，省略了主语。"表现层"其实指的是"资源"（Resources）的"表现层"。所谓"资源"，就是网络上的一个实体，或者说是网络上的一个具体信息。它可以是一段文本、一张图片、一首歌曲、一种服务，总之就是一个具体的实在。你可以用一个URI（统一资源标识符）指向资源，可以使用HTTP请求方法操作资源。URI可以进一步划分为统一资源名URN(代表资源的名称，定义资源的身份)，统一资源定位符URL（代表资源的地址，提供查找该资源的方式）。我们定位互联网上的一个资源普遍采用的就是URL。例如　http://www.pythondoc.com/flask/index.html　该URL就定位到flask的中文官方文档，而这个文档文件就是一个资源。
表现层：资源的表现形式，　"资源"是一种信息实体，它可以有多种外在表现形式。我们把"资源"具体呈现出来的形式，叫做它的"表现层"（Representation）。比如，文本可以用txt格式表现，也可以用HTML格式、XML格式、JSON格式表现，甚至可以采用二进制格式；图片可以用JPG格式表现，也可以用PNG格式表现。URI只代表资源的实体，不代表它的形式。严格地说，有些网址最后的".html"后缀名是不必要的，因为这个后缀名表示格式，属于"表现层"范畴，而URL应该只代表"资源"的位置。它的具体表现形式，应该在HTTP请求的头信息中用Accept（能够接受的的数据类型）和Content-Type（POST和PUT请求的数据类型）字段指定，这两个字段才是对"表现层"的描述。通俗讲，我这个资源应该以什么形式展示给客户端，像我们系统在POST请求的时候请求头中，Accept:application/json ，text/plain ，/和Content-Type:application/json ，我们规定了JSON 的资源表示形式。
状态转化：让服务端的资源进行变化。访问一个资源，代表着客户端与服务器的一个互动过程。在这个过程中势必涉及到数据变化。如果客户端想
让服务端数据发生变化，用到HTTP协议里面表示操作方式的动词：GET、POST、PUT、DELETE。它们分别对应四种基本操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源。
HTTP Status Code传递Server的状态信息。该服务是否有效，该操作是否被服务端正确执行，是通过Status Code表示的。比如最常用的 200 表示成功，500 表示Server内部错误等。如果出错则返回错误信息和　400 BadRequest，由客户端处理异常。
综述

（1）每一个URL代表一种资源；
（2）客户端和服务器之间，传递这种资源的某种表现层；
（3）客户端通过四个HTTP动词，对服务器端资源进行操作，实现"表现层状态转化"。

RESTful API 设计规范

API一旦发布，其结构将很难修改，因此设计一个符合规范，灵活友好的API，是一件非常重要的事情。

以资源为中心的 URL 设计

资源是 Restful API 的核心元素，所有的操作都是针对特定资源进行的。
/users
/users/1
/tasks
/users/tasks
/users/tasks/1

使用名词来表示资源

URL不应该包含动词。动词应该通过不同的HTTP方法来体现
常见错误用法
POST /users/1/create
POST /users/1/delete
正确的用法为
GET /users
GET /users/1
PUT /users/1

关注请求头

一定要看请求头的信息，并且给予正确的状态码。假设服务器端只能返回JSON格式，如果客户端的头信息的Accept字段要求返回application/xml，这个时候就不应该返回application/json类型的数据，而是返回406 错误信息。

合理使用请求方法、状态码和返回信息。

GET（SELECT）：用于从服务器获取资源信息（一项或多项）。
1 完成请求后，返回状态码200 OK
2 查询多项，完成请求后，返回被请求资源的列表（对象组成的数组）
3 查询一项，完成请求后，返回被请求资源的详情（对象）
POST（CREATE）：用于在服务器新建一个资源。
1 创建完成后，返回状态码201 Created
2 完成请求后，返回被创建资源的详细信息
PUT（UPDATE）：用于完整的替换资源或者创建指定身份的资源，比如创建id为123的某个资源。
1 如果创建了资源，则返回201　Created
2 如果替换了资源，则返回200 OK
3 返回被修改资源的详细信息
DELETE（DELETE）：用于从服务器删除资源。
删除成功，返回状态码　204 No Content

如未完成查询，创建，更新，删除等不符合预期的操，即客户端发出的请求有错误，返回定义好的错误信息并且返回错误码400 Bad Request

还有几个不常用的方法

PATCH（UPDATE）：用于局部更新资源。
HEAD：获取资源的元数据。
OPTIONS：获取资源支持的所有HTTP方法。

保证返回结果具有高可读性

对输出结果不在包装

body中应该直接放数据，不要多层封装
错误例子

HTTP/1.1 200 OK
{
    "success":"true",
    "data":{
        "id":1,
        "name":"chaozi"
    }
}

正确的例子应该是

HTTP/1.1 200 OK
{
    "id":1,
    "name":"chaozi"
}

使用嵌套对象序列化
对象应该合理嵌套，不应该都在一个层次上。如下格式是不正确的

{
    "id":1,
    "author":"chaozi",
    "artical_id":"1001",
    "artical_name":"artical1",
    "artical_content":"this is a artical"
}

把相关联的资源信息内联在一起。应该把artical作为一个键

{
    "id":1,
    "author":"chaozi",
    "artical":{
        "id":"10001",
        "name":"artical1",
        "content":"this is a artical"
    }
}

信息过滤

URL 通常越简洁越好，对结果的过滤，排序和搜索都应该通过参数实现

?limit=10：指定返回记录的数量。
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件。