美文网首页
[server-notes] RESTful api

[server-notes] RESTful api

作者: liwuwuzhi | 来源:发表于2020-12-22 14:17 被阅读0次

    1. 什么是REST

    REST全称是Representational State Transfer,中文意思是 “表述性状态转移”。 它首次出现在2000年Roy Fielding的博士论文中,Roy Fielding是HTTP规范的主要编写者之一。

    REST本身并没有创造新的技术、组件或服务,而隐藏在RESTful背后的理念就是使用Web的现有特征和能力, 更好地使用现有Web标准中的一些准则和约束。
    虽然REST本身受Web技术的影响很深, 但是理论上REST架构风格并不是绑定在HTTP上,只不过目前HTTP是唯一与REST相关的实例。 所以我们这里描述的REST也是通过HTTP实现的REST。

    2. 理解RESTful

    要理解RESTful架构,需要理解Representational State Transfer这个词组到底是什么意思,它的每一个词都有些什么涵义。

    下面我们结合REST原则,围绕资源展开讨论,从资源的定义、获取、表述、关联、状态变迁等角度,列举一些关键概念并加以解释。

    资源与URI
    统一资源接口
    资源的表述
    资源的链接
    状态的转移

    2. 1 资源与URI

    REST全称是表述性状态转移,那究竟指的是什么的表述? 其实指的就是资源。
    任何事物,只要有被引用到的必要,它就是一个资源。

    要让一个资源可以被识别,需要有个唯一标识,在Web中这个唯一标识就是URI(Uniform Resource Identifier)。

    URI既可以看成是资源的地址,也可以看成是资源的名称。

    URI的设计应该遵循可寻址性原则,具有自描述性,需要在形式上给人以直觉上的关联(以github为例)。

    • 使用_或-来让URI可读性更好
    • 使用/来表示资源的层级关系
    • 使用?用来过滤资源
      很多人只是把?简单的当做是参数的传递,很容易造成URI过于复杂、难以理解。
      可以把?用于对资源的过滤, 例如/git/git/pulls用来表示git项目的所有推入请求,而/pulls?state=closed用来表示git项目中已经关闭的推入请求, 这种URL通常对应的是一些特定条件的查询结果或算法运算结果。
    • ,或;可以用来表示同级资源的关系
      例如可以用 /git/git/compare/master…next 比较某个文件在随意两次提交记录之间的差异。
    2. 2 统一资源接口

    接口应该使用标准的HTTP方法如GET,PUT和POST,并遵循这些方法的语义。
    如果按照HTTP方法的语义来暴露资源,那么接口将会拥有安全性幂等性的特性,例如
    GET和HEAD请求都是安全的, 无论请求多少次,都不会改变服务器状态;
    GET、HEAD、PUT和DELETE请求都是幂等的,无论对资源操作多少次, 结果总是一样的,后面的请求并不会产生比第一次更多的影响。

    • 统一资源接口对URI有什么指导意义?
      统一资源接口要求使用标准的HTTP方法对资源进行操作,所以URI只应该来表示资源的名称,而不应该包括资源的操作。

    • 直接忽视缓存可取吗?
      即使你按各个动词的原本意图来使用它们,你仍可以轻易禁止缓存机制。 最简单的做法就是在你的HTTP响应里增加这样一个报头: Cache-control: no-cache。 但是,同时你也对失去了高效的缓存与再验证的支持(使用Etag等机制)。
      对于客户端来说,在为一个REST式服务实现程序客户端时,也应该充分利用现有的缓存机制,以免每次都重新获取表示。

    • 响应代码的处理有必要吗?
      HTTP的响应代码可用于应付不同场合,正确使用这些状态代码意味着客户端与服务器可以在一个具备较丰富语义的层次上进行沟通。
      例如,201("Created")响应代码表明已经创建了一个新的资源,其URI在Location响应报头里。
      假如你不利用HTTP状态代码丰富的应用语义,那么你将错失提高重用性、增强互操作性和提升松耦合性的机会。
      如果这些所谓的RESTful应用必须通过响应实体才能给出错误信息,那么SOAP就是这样的了,它就能够满足了

    2. 3 资源的表述

    上面提到,客户端通过HTTP方法可以获取资源,是吧? 不,确切的说,客户端获取的只是资源的表述而已。 资源在外界的具体呈现,可以有多种表述形式,在客户端和服务端之间传送的也是资源的表述,而不是资源本身。
    例如文本资源可以采用html、xml、json等格式,图片可以使用PNG或JPG展现出来。

    资源的表述包括数据和描述数据的元数据,例如,HTTP头"Content-Type" 就是这样一个元数据属性。

    那么客户端如何知道服务端提供哪种表述形式呢?

    通过HTTP内容协商,客户端可以通过Accept头请求一种特定格式的表述,服务端则通过Content-Type告诉客户端资源的表述形式。

    以github为例,请求某组织资源的json格式的表述形式:

    2. 4 资源的链接
    2. 5 状态的转移
    2. 5.1 应用状态与资源状态
    2. 5.2 应用状态的转移

    RESTful API 设计指南
    RESTful API 最佳实践
    REST API 与 koa-router

    相关文章

      网友评论

          本文标题:[server-notes] RESTful api

          本文链接:https://www.haomeiwen.com/subject/uxmwdktx.html