今天完成的任务：学习任务二的restful风格的接口命名规则。

REST是一个术语的缩写，REpresentational State Transfer，中文直译是“表征状态转移”。
REST是一套风格约定，RESTful是它的形容词形式。比如一套实现了REST风格的接口，可以称之为RESTful接口。

一、API的url

URL 用来定位资源，跟要进行的操作区分开，这就意味着URL不该有任何动词。

1.1 下面示例中的 get、create、search 等动词，都不应该出现在 REST 架构的后端接口路径中。比如：

/api/getUser

/api/createApp

/api/searchResult

/api/deleteAllUsers

1.2 当我们需要对单个用户进行操作时，根据操作的方式不同可能需要下面的这些接口：

/api/getUser （用来获取某个用户的信息，还需要以参数方式传入用户 id 信息）

/api/updateUser （用来更新用户信息）

/api/deleteUser （用来删除单个用户）

/api/resetUser （重置用户的信息）

1.3 可能在更新用户不同信息时，提供不同的接口，比如：

/api/updateUserName

/api/updateUserEmail

/api/updateUser

1.4 总结：

以上三种情况的弊端在于：首先加上了动词，肯定是使 URL 更长了；其次对一个资源实体进行不同的操作就是一个不同的 URL，造成 URL 过多难以管理。

其实当你回过头看“URL”这个术语的定义时，更能理解这一点。URL 的意思是统一资源定位符，这个术语已经清晰的表明，一个 URL 应该用来定位资源，而不应该掺入对操作行为的描述。

在 REST 架构的链接应该是这个样子：

URL 中不应该出现任何表示操作的动词，链接只用于对应资源；

URL 中应该单复数区分，推荐的实践是永远只用复数；比如GET /api/users表示获取用户的列表；如果获取单个资源，传入 ID，比如/api/users/123表示获取单个用户的信息；

按照资源的逻辑层级，对 URL 进行嵌套，比如一个用户属于某个团队，而这个团队也是众多团队之一；那么获取这个用户的接口可能是这样：GET /api/teams/123/members/234 表示获取 id 为 123 的小组下，id 为234 的成员信息。

按照类似的规则，可以写出如下的接口

/api/teams （对应团队列表）

/api/teams/123 （对应 ID 为 123 的团队）

/api/teams/123/members （对应 ID 为 123 的团队下的成员列表）

/api/teams/123/members/456 （对应 ID 为 123 的团队下 ID 未 456 的成员）

二、API 请求的方法

实际上，我们不只有GET 和 POST 可用，在 REST 架构中，有以下几个重要的请求方法：GET，POST，PUT，PATCH，DELETE。

接下来主要介绍PUT，PATCH和DELETE。

2.1 UPDATE（PUT和PATCH）

【Update】资源的更新，用于更新的 HTTP 方法有两个，PUT 和 PATCH。他们都应当被实现为幂等方法，即多次同样的更新请求应当对服务器产生同样的副作用。

PUT 用于更新资源的全部信息，在请求的 body 中需要传入修改后的全部资源主体；

PATCH 用于局部更新，在 body 中只需要传入需要改动的资源字段。

PATCH 的作用在于如果一个资源有很多字段，在进行局部更新时，只需要传入需要修改的字段即可。否则在用 PUT 的情况下，你不得不将整个资源模型全都发送回服务器，造成网络资源的极大浪费。

2.2 DELETE

【Delete】资源的删除，相应的请求 HTTP 方法就是 DELETE。这个也应当被实现为一个幂等的方法。如：DELETE /api/users/123

用于删除服务器上 ID 为 123 的资源，多次请求产生副作用都是，是服务器上 ID 为 123 的资源不存在。

四、正确示例

标准的格式是

http(s): //server.com /app-name /{version} /{domain} /{rest-convention}

{version}代表api的版本信息。

{domain}是一个你可以用来定义任何技术的区域(例如：安全-允许指定的用户可以访问这个区域)或者业务上的原因(例如：同样的功能在同一个前缀之下。)

{rest-convention} 代表这个域(domain)下，约定的rest接口集合。

单资源( singular-resourceX )

url样例：order/ (order即指那个单独的资源X)

GET – 返回一个新的order

POST- 创建一个新的order，从post请求携带的内容获取值。

单资源带id(singular-resourceX/{id} )

URL样例：order/1 ( order即指那个单独的资源X )

GET – 返回id是1的order

DELETE – 删除id是1的order

PUT – 更新id是1的order，order的值从请求的内容体中获取。

复数资源(plural-resourceX/)

URL样例:orders/

GET – 返回所有orders

复数资源查找(plural-resourceX/search)

URL样例：orders/search?name=123

GET – 返回所有满足查询条件的order资源。(实例查询，无关联) – order名字等于123的。

复数资源查找(plural-resourceX/searchByXXX)

URL样例：orders/searchByItems?name=ipad

GET – 将返回所有满足自定义查询的orders – 获取所有与items名字是ipad相关联的orders。

单数资源(singular-resourceX/{id}/pluralY)

URL样例：order/1/items/ (这里order即为资源X，items是复数资源Y)

GET – 将返回所有与order id 是1关联的items。

singular-resourceX/{id}/singular-resourceY/

URL样例：order/1/item/

GET – 返回一个瞬时的新的与order id是1关联的item实例。

POST – 创建一个与order id 是1关联的item实例。Item的值从post请求体中获取。

singular-resourceX/{id}/singular-resourceY/{id}/singular-resourceZ/

URL样例：order/1/item/2/package/

GET – 返回一个瞬时的新的与item2和order1关联的package实例。

POST – 创建一个新的与item 2和order1关联的package实例，package的值从post请求体中获得。

四、其他规范

一些其他规范：
规则1：URI结尾不应包含（/）
规则2：正斜杠分隔符（/）必须用来指示层级关系
规则3：应使用连字符（ - ）来提高URI的可读性
规则4：不得在URI中使用下划线（_）
规则5：URI路径中全都使用小写字母

收获：简单理解了命名规范了。

明天的目标：接着把任务一的深度思考学习。