RESTful Web服务架构标准

2020-02-07 08:44栏目:龙竞技官网
TAG:

原文:

[译] REST API URI 设计的七准则

摘要:本文属于原创,欢迎转载,转载请保留出处:https://github.com/jasonGeng88/blog

原文:http://blog.restcase.com/7-rules-for-rest-api-uri-design

在了解 REST API URI 设计的规则之前,让我们快速过一下我们将要讨论的一些术语。

脑图


RESTful

在了解 REST API URI 设计的规则之前,让我们快速过一下我们将要讨论的一些术语。

URI

REST API 使用统一资源标识符(URI)来寻址资源。在今天的网站上,URI 设计范围从可以清楚地传达API的资源模型,如:

http://api.example.com/louvre/leonardo-da-vinci/mona-lisa

到那些难以让人理解的,比如:

http://api.example.com/68dd0-a9d3-11e0-9f1c-0800200c9a66

Tim Berners-Lee 在他的“Web架构公理”列表中列出了关于 URI 的不透明度的注释:

***唯一可以使用标识符的是对对象的引用。当你没有取消引用时,你不应该查看 URI 字符串的内容以获取其他信息。

  • Tim Berners-Lee***

客户端必须遵循 Web 的链接范例,将 URI 视为不透明标识符。

REST API 设计人员应该创建 URI,将 REST API 的资源模型传达给潜在的客户端开发人员。 在这篇文章中,我将尝试为 REST API URsI 引入一套设计规则。

在深入了解规则之前,先看一下在 RFC 3986 中定义的通用 URI 语法,如下所示:

URI = scheme "://" authority "/" path ["?" query] ["#" fragment]

目录


  1. 什么是RESTful

  2. HTTP方法

  3. 清晰的RESTful API

  4. RESTful 消息

  5. RESTful URI

  6. RESTful 会话

REST API 使用统一资源标识符来寻址资源。在今天的网站上,URI 设计范围从可以清楚地传达API的资源模型,如:

规则#1:URI中不应包含尾随的斜杠(/)

这是作为 URI 路径中最后一个字符的最重要的规则之一,正斜杠(/)不会增加语义值,并可能导致混淆。 REST API 不应该期望有一个尾部的斜杠,并且不应该将它们包含在它们提供给客户端的链接中。

许多 Web 组件和框架将平等对待以下两个 URI:

http://api.canvas.com/shapes/

http://api.canvas.com/shapes

什么是RESTful


  • REST是一种基于web标准软件架构标准
  • 在这个标准中,把一切调用或请求的对象,都视为资源,所以,其中心思想,一切皆资源
  • 客户端与服务端之间以HTTP处理数据通信
  • REST架构中,服务端提供对资源的访问,而客户端,访问并呈现资源
  • 所以,REST架构中,主要参与者,就是客户端与服务端
  • 服务端,负责着一切对资源的操作,这些操作会被封装成一个RESTful API,用于客户端请求
  • URIs是REST架构中的全局ID标识

然而,URI 中的每个字符都会被计入作为资源的唯一标识。

两个不同的 URI 映射到两个不同的资源。如果 URI 不同,那么资源也会不同,反之亦然。因此,REST API 必须生成和传达清晰的 URI,并且不应容忍任何客户端尝试去对一个资源进行模糊的标识。

更多的API可能会将客户端重定向到末尾没有斜杠的 URI 上,(他们也可能会返回 301 - 用于重新定位资源的 “Moved Permanently”)。

HTTP 方法


  • GET 提供资源的只读访问
  • PUT 创建一个新资源
  • DELETE 用于移除一个资源
  • POST 更新现有资源或者创建新资源
  • OPTIONS 用于获取该资源所支持的操作

到那些难以让人理解的,比如:

规则#2:正斜杠分隔符(/)必须用于指示层次关系

在 URI 的路径部分的正斜杠(/),用于表示资源之间的层次关系。

例如:

http://api.canvas.com/shapes/polygons/quadrilaterals/squares

清晰的RESTful API


RESTful API

如图,操作类型中,只读指不会更改资源,幂等指多次执行产生的影响与与第一次执行产生的影响是一样的,N/A在表格中,可理解为 / 即划掉此格,不用理会此格

这里顺便解释一个概念:幂等函数,或幂等方法,是指可以使用相同参数重复执行,并能获得相同结果的函数。

REST服务器对资源的表现形式应该是包容的,即使用什么格式传递数据,应该由客户端来指定:有客户端要xml而有的客户端要json

规则#3:应使用连字符( - )来提高 URI 的可读性

为了使你的 URI 容易被人检索和解释,请使用连字符( - )来提高长路径段中名称的可读性。在任何你将使用英文的空格或连字号的地方,在URI中都应该使用连字符来替换。

例如:

http://api.example.com/blogs/guy-levin/posts/this-is-my-first-post

RESTful消息


在REST服务中,HTTP请求与响应就是作为消息传递的技术
一个REST消息包含消息数据和元数据(为描述数据的数据)

  • 请求

HTTP Request

Verb(动作) 表明HTTP方法,如GET、POST等
URI 表示服务器上资源的统一资源标识符
HTTP VERSION (http版本) 如 http v1.1
请求头,包含HTTP请求消息的元数据,它是键值对(key-value),比如客户端类型
请求体,消息内容和要求的REST服务器返回资源的表示形式
  • 响应

HTTP Response

Response Code(状态/响应码),表明请求资源的服务器状态,比如404 500等
HTTP VERSION http版本
响应头 返回响应的元数据 如服务器类型等,也是键值对
响应体 以客户端想要的资源表现形式返回资源

版权声明:本文由龙竞技官网发布于龙竞技官网,转载请注明出处:RESTful Web服务架构标准