RESTful API知识整理

不是标准,是设计风格

REST(英文:Representational State Transfer,简称REST),通常应用在web应用程序中,提供一套满足特定的约束和原则的接口,用于客户端和服务器交互。REST并没有一个明确的标准,而更像是一种设计的风格。

来源于一篇论文

Roy Felding 在他论文 network based software architectures 中首次介绍了这些原则。

文章最后是论文下载链接(中文版)。80多页,概念很多,看起来有点无趣。哈哈。

意义深远

就像REST的作者所说的那样:

“本文研究计算机科学两大前沿—-软件和网络—-的交叉点。长期以来,软件研究主要关注软件设计的分类、设计方法的演化,很少客观地评估不同的设计选择对系统行为的影响。而相反地,网络研究主要关注系统之间通信行为的细节、如何改进特定通信机制的表现,常常忽视了一个事实,那就是改变应用程序的互动风格比改变互动协议,对整体表现有更大的影响。我这篇文章的写作目的,就是想在符合架构原理的前提下,理解和评估以网络为基础的应用软件的架构设计,得到一个功能强、性能好、适宜通信的架构。”

基于HTTP

因为大部分用于web应用,底层通讯肯定还是http协议。比如GET,POST那些。这些也是客户端唯一可以访问服务端的方式。

URI

HTTP协议中有个很重要的概念:URI(注意不是URL,二者区别请自行搜索学习)

URI,是uniform resource identifier,统一资源标识符,用来唯一的标识一个资源。在RESTful架构中,每个网址代表一种资源(resource)。

网上的一些例子,

ftp://ftp.is.co.za/rfc/rfc1808.txt (also a URL because of the protocol)
http://www.ietf.org/rfc/rfc2396.txt (also a URL because of the protocol)
ldap://[2001:db8::7]/c=GB?objectClass?one (also a URL because of the protocol)
mailto:John.Doe@example.com (also a URL because of the protocol)
news:comp.infosystems.www.servers.unix (also a URL because of the protocol)
tel:+1-816-555-1212
telnet://192.0.2.16:80/ (also a URL because of the protocol)
urn:oasis:names:specification:docbook:dtd:xml:4.1.2

从上面这个例子也可以看出,大部分REST API都是在某个域名之下,这也是实现REST API一个常用的方式。

知乎上的一个例子

比如在JDK中sun公司提供的简易HttpServer实现中

public void handle(final HttpExchange exchange)throws Exception

方法中,根据exchange对象可以拿到访问Http请求的URI对象,

ps:
http://127.0.0.1:8080/cmd_helloworld/?name=guowuxin

此时URI uri = exchange.getRequestURI();

通过uri可以拿到连接的各部分内容:

uri.getPath() --------------------> /cmd_helloworld 注意有斜杠
uri.getQuery()----------------------> name=guowuxin

作者:郭无心
链接:https://www.zhihu.com/question/21950864/answer/66779836
来源:知乎
著作权归作者所有,转载请联系作者获得授权。

应用实例

微博 API Error code

微博 API Error code

论文里对状态码有描述:

同样地,HTTP需要一个通用的规则来解释新的响应状态码,这样新的响应能够进行部 署而不会严重损害老的客户端。因此我们扩大了这个规则,规定每个状态码属于一个类别, 通过三位十进制数的第一位数字来表示:100-199表示消息中包含一个临时的信息响应, 200-299表示请求成功,300-399表示请求需要被重定向到另一个资源,400-499表示客户 端发生了一个不应该重复的错误,500-599表示服务器端遇到了一个错误,但是客户端稍后 可以得到一个更好的响应(或者通过某个其他服务器)。如果接收者不理解一个消息中的状 态码的特定语义,那么它们必须将该状态码按照与同一类别中状态码为x00时相同的方式来 处理。就像是方法名称的规则一样,这个可扩展性的规则在当前的架构上添加了一个需求, 这样架构就能够预见到未来的改变。改变因此能够被部署在一个现有架构之上,而无须害怕 出现不利的组件反应(adverse component reactions)。

Github API v3

Github API v3

比如我想获取一个github上的项目的详细信息,通过API可以拿到。

比如获取用户的基本信息,示例如下:

# GET /users/defunkt
curl https://api.github.com/users/defunkt

{
  "login": "defunkt",
  "id": 2,
  "url": "https://api.github.com/users/defunkt",
  "html_url": "https://github.com/defunkt",
  ...
}

另外有一点,Github API把版本号放在了URL的路径中,这个在很多参考资料中都不建议。一个很重要的原因是这样的设计,版本更新都会导致URL更新。不过这样设计的好处是方便直观,也有人推崇。

尽量使用JSON,避免使用XML

如果你做的项目多,会发现REST+JSON基本是个标准组合了。之所以没有用XML我觉得是JSON相对于XML更加简单,易读。作为开发者,我个人的经验是如果API响应的数据是JSON,我更容易发现里面的错误。

RESTful架构有一些典型的设计误区

最常见的一种设计错误,就是URI包含动词。因为”资源”表示一种实体,所以应该是名词,URI不应该有动词,动词应该放在HTTP协议中。举例来说,某个URI是/posts/show/1,其中show是动词,这个URI就设计错了,正确的写法应该是/posts/1,然后用GET方法表示show。

如果某些动作是HTTP动词表示不了的,你就应该把动作做成一种资源。比如网上汇款,从账户1向账户2汇款500元,错误的URI是:

  POST /accounts/1/transfer/500/to/2

正确的写法是把动词transfer改成名词transaction,资源不能是动词,但是可以是一种服务:

  POST /transaction HTTP/1.1
  Host: 127.0.0.1
  
  from=1&to=2&amount=500.00

另一个设计误区,就是在URI中加入版本号:

  http://www.example.com/app/1.0/foo
  http://www.example.com/app/1.1/foo
  http://www.example.com/app/2.0/foo

因为不同的版本,可以理解成同一种资源的不同表现形式,所以应该采用同一个URI。版本号可以在HTTP请求头信息的Accept字段中进行区分(参见Versioning REST Services):

  Accept: vnd.example-com.foo+json; version=1.0
  Accept: vnd.example-com.foo+json; version=1.1
  Accept: vnd.example-com.foo+json; version=2.0

一些好玩有用的资料

搜索API
APIs.io – the API search engine
ProgrammableWeb

Nytimes,使用这个API,开发者可以调用到几百万份结构化过的数据,从1981 年至今,纽约时报报道的事件,畅销书,甚至房地产等等
Nytimes

参考

  1. 理解RESTful架构
  2. 架构风格与基于网络的软件架构设计.pdf
  3. Web API Design
  4. Principles of good RESTful API Design
    原文作者:Pony小马
    原文地址: https://www.jianshu.com/p/3251ed5ab87c
    本文转自网络文章,转载此文章仅为分享知识,如有侵权,请联系博主进行删除。
点赞