细说REST API

时间:2024-01-01 12:00:03

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 API

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

细说REST API

总之,对于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设计技巧经验总结