细说REST API

Posted 2020-08-29 Simple is Awesome

1. REST概述

REST（英文：Representational State Transfer，又称具象状态传输）是Roy Thomas Fielding博士于2000年在他的博士论文中提出来的一种万维网软件架构风格，目的是便于不同软件/程序在网络（例如互联网）中互相传递信息。目前在三种主流的Web服务实现方案中，因为REST模式与复杂的SOAP和XML-RPC相比更加简洁，越来越多的web服务开始采用REST风格设计和实现。

要点及标准
    - 需要注意的是，REST是设计风格而不是标准。REST通常基于使用HTTP，URI，XML以及html这些现有的广泛流行的协议和标准。
    - 资源是由URI来指定。
    - 对资源的操作包括获取、创建、修改和删除资源，这些操作正好对应HTTP协议提供的GET、POST、PUT和DELETE方法。
    - 通过操作资源的表现形式来操作资源。
    - 资源的表现形式则是XML或者HTML，取决于读者是机器还是人，是消费web服务的客户软件还是web浏览器。当然也可以是任何其他的格式，如：JSON。

REST架构风格最重要的架构约束有6个：
    * 客户-服务器（Client-Server）：通信只能由客户端单方面发起，表现为请求-响应的形式。
    * 无状态（Stateless）：通信的会话状态（Session State）应该全部由客户端负责维护。
    * 缓存（Cache）： 响应内容可以在通信链的某处被缓存，以改善网络效率。
    * 统一接口（Uniform Interface）： 通信链的组件之间通过统一的接口相互通信，以提高交互的可见性。
    * 分层系统（Layered System）：通过限制组件的行为（即每个组件只能“看到”与其交互的紧邻层），将架构分解为若干等级的层。
    * 按需代码（Code-On-Demand，可选）： 支持通过下载并执行一些代码（例如Java Applet、Flash或javascript），对客户端的功能进行扩展。

 

2. REST API

REST风格的软件架构，常常用于Web服务中。符合REST设计风格的Web API称为RESTful API。它从以下三个方面资源进行定义：
    - 直观简短的资源地址：URI，比如：http://example.com/resources/。
    - 传输的资源：Web服务接受与返回的互联网媒体类型，比如：JSON，XML，YAML等。
    - 对资源的操作：Web服务在该资源上所支持的一系列请求方法（比如：POST，GET，PUT或DELETE）。

总之，对于REST API的理解，主要包含如下几个方面：
(1) 资源通过URI描述
(2) 通过json或xml描述数据对象或属性
(3) 使用HTTP方法进行消息传递，如: GET，POST，PUT，DELETE分别对应着对资源的获取，创建，更新，删除
(4) 在服务器端不保存交互客户端上下文信息，而由客户端保存会话状态

另外，规范的的REST API必须使用正确的HTTP状态码（这一点非常重要，涉及到REST API的规范性和可维护性），如：
* 1XX - informational
* 2XX - success
* 3XX - redirection
* 4XX - client error
* 5XX - server error
更加详细的HTTP状态码请参考rfc2616，详见：https://tools.ietf.org/html/rfc2616。而且，必要的时候可通过HTTP消息头Accept和Content-Type描述传递的内容。

最后，REST API还应该进行版本管理。

 

3. 总结

不像基于SOAP的Web服务，RESTful Web服务并没有“正式”的标准。这是因为REST是一种架构，而SOAP只是一个协议。
虽然REST不是一个标准，但大部分RESTful Web服务实现会使用HTTP、URI、JSON和XML等各种标准。

 

【参考】

https://zh.wikipedia.org/wiki/REST 维基百科，自由的百科全书
http://rest.elkstein.org/2008/02/what-is-rest.html Learn REST: A Tutorial
https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
https://spring.io/understanding/REST Understanding REST
http://www.infoq.com/cn/articles/understanding-restful-style 理解本真的REST架构风格
https://coyee.com/article/11302-good-practices-in-api-design API 设计的最佳实践
https://zhuanlan.zhihu.com/p/20034107 撰写安全合格的REST API
http://geek.csdn.net/news/detail/201132?url_type=39&object_type=webpage&pos=1 RESTful API设计技巧经验总结