学习笔记 - Rest full API 总结

REST API 概念    Representational State Transfer

一种软件架构风格、设计风格，而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。

REST 指的是一组架构约束条件和原则。满足这些约束条件和原则的应用程序或设计就是 RESTful。

REST中的资源所指的不是数据，而是数据和表现形式的组合，比如“最新访问的10位会员”和“最活跃的10位会员”在数据上可能有重叠或者完全相同，而由于他们的表现形式不同，所以被归为不同的资源，这也就是为什么REST的全名是Representational State Transfer的原因。

REST API的设计原则

1. 服务器-客户端原则 
- 在整个应用中，需要将客户端与服务器分开，两者之间尽量解耦合，都可以分开演进 
2. 无状态 
- 客户端的状态不会在服务端存储。每个session的信息只在客户端存储。 
3. 可缓存 
- 同样的请求应该有同样的返回，使得请求可缓存。 
4. 分层 
- 客户端无法分辨自己是否直接连接到服务器或者是中间层。这个性质可以进一步增强可扩展性。 
5. 统一的接口设计 

接口的设计原则：

      1. 识别资源 
      - 资源通过请求进行识别。识别后的资源会在服务端进行转换格式，返回到客户端。返回的格式与数据本身无关。 
      2. 通过资源的表达来操作资源 
      - 客户端需要保存完整的资源，以及必要的元信息（MetaData），使得这些信息足够对资源进行修改或删除。 
      3. 自解释的消息 
      - 每个消息需要包含足够的信息来决定如何处理这个消息。例如在指定parser的时候需要使用Internet media type来指定。 
      4. HATEOAS 
      - 字面意思是，超媒体作为应用状态转移的引擎 
      - 从最开始的一共请求开始，每次返回的请求能够告诉客户端，服务端还有哪些资源提供。有时可以返回带有超链接的文                  字。 
      - 客户端不需要根据服务端的数据结构进行任何定制

HTTP Method 与  API 说明

GET：      获取资源列表或单个资源

PUT:         将指定的资源进行替换

PATCH:    将指定的资源局部更新

POST：    新建一条记录。

DELETE：删除对应记录

Patch

2010年  HTTP协议中增加了一个操作 ：Patch

Patch 为何不幂等呢？ 
有两个解释，一个是，在两次patch请求之间，如果对应资源有改变，那么两次patch请求造成的结果不同， 
返回的object也不同。 
另一个解释是，当资源模型中有一个列表时，如果多次执行 add 操作，那么这个列表几次操作后得到的结果也不同。

RESTful中的PUT和PATCH实践

在UserApi中，有这样三个接口 
1. PUT /users/{id} 更新用户信息 
2. PATCH /users/role/{id} 更新用户角色 
3. PATCH /users/status/{id} 更新用户状态

在这三个接口便可以看出PUT和PATCH的区别 
PUT方法主要是用来更新整个资源的，而PATCH方法主要是用来执行某项操作并更新资源的某些字段

• PUT /users/{id} 更新用户信息

要求是系统管理员、管理员或者是用户本人，才能使用该接口

• PATCH /users/role/{id} 更新用户角色

要求是系统管理员才能使用该接口

• PATCH /users/status/{id} 更新用户状态

要求是系统管理员、管理员才能使用该接口

REST API: 该使用部分更新还是全部更新？

关于Rest API更新资源的讨论： 
当更新一个对象的时候，是否要将完整object全部信息重新提交到服务器？还是只提交部分内容？

一种是完整提交的方案 
              认为在前端需要保存完整的object数据，在前端由用户做更改， 
              之后将完整的object重新使用PUT方法传回服务器。
好处   ： API幂等      后端设计简单
弊端   ： 传送数据量过大

一种是部分提交的方案 
               认为每次在前端更改内容的时候，只将更新的内容提交到服务器即可
好处   ： 交互流量少
弊端   ： 当该模型某些字段可为null时，如何知道没有指定的字段，是要求置为Null还是保持原样?

参考：

https://blog.csdn.net/qq_35264464/article/details/79490618 

https://blog.csdn.net/bychahaha/article/details/53271394

https://blog.csdn.net/u013731455/article/details/56278168

https://blog.csdn.net/chlu113/article/details/51853331 HTTP协议详解