rest接口设计（rest接口协议）

本篇文章给大家谈谈rest接口设计，以及rest接口协议对应的知识点，希望对各位有所帮助，不要忘了收藏本站喔。 今天给各位分享rest接口设计的知识，其中也会对rest接口协议进行解释，如果能碰巧解决你现在面临的问题，别忘了关注本站，现在开始吧！

本文目录一览：

• 1、理解 REST 接口规范
• 2、REST接口是什么？（译文）
• 3、REST接口规范
• 4、如何更好的设计RESTful API

理解 REST 接口规范

REST 全称 Representational State Transfer（表现层状态转换），是 Roy Thomas Fielding 博士于 2000 年在他的博士论文中提出来的一种软件构建风格。

我们先来看两个不好的接口设计

符合 REST 风格的接口，应该遵循 url 表示资源的定位，http method 请求方式表示对资源的操作，请求响应的状态码，表示请求的结果。

下面我们来举一些简单的示例，来演示一下正确的接口定义规范

客户列表

过滤选项，可以通过 query 参数，追加在地址后面，如：

创建客户

单个客户详情

更新客户

删除客户

多级资源：获取某个客户下的所有订单

其它注意事项

参考资料

如果这篇文章对您有帮助，记得给作者点个赞，谢谢！

REST接口是什么？（译文）

—— evilrescuer 翻译自 Ruben Verborgh 写的 《What is a REST API?》

REST是不同于其他系统的一种描述网页如何架构的方法。

Web是一种可以轻易地通过你的浏览器访问的，位于因特网最上层的信息网络。在许多方面，它有着和其他计算机系统不同的架构。

REST是一种用来设计系统（如Web）的架构风格。REST最典型的特征就是 统一接口的四个约束。 REST接口遵循这四个规范。

约束1：提供通过资源的访问

在典型的计算机系统中，客户端和服务器交换命令：做这个，做那个。假设我们想用非REST的方式模拟一个to-do列表，用技术语言，这可能长这样：

非REST

注意，它的的确确是一条指令：改变某个东西。
但“changeTodoList”不是一个东西，不是一个资源。

在REST架构风格里，服务器仅仅提供资源。资源是概念上客户端和服务器通讯的东西。

REST

上面这串东西不是一个命令，而是一个资源、一个东西的地址。你可以使用这个地址，用标准的方法去操纵to-do列表，而不是用特定接口的命令。

约束2：通过陈述表现资源

一个资源是我们能用不同的格式描述的东西。例如，人们可能想理解由浏览器转换成的可读布局的HTML版本。但有时Web上的接口是提供给机器使用的，它们需要一个不同的格式，如JSON。

通过非REST的方式，不同的格式具有不同的地址：

非REST

那么问题来了。这两个使用不同格式的系统彼此间无法通讯，因为它们在同一个东西上用不同的地址。

在REST系统中，地址与东西一致，而非格式，所以所有的系统在同一个东西上用同一个地址。那它们怎么获取不同格式的这个东西呢？它们明确地提出请求！

REST

使上面的方案可行的技术被称为 内容协商 。

约束3：交换自描述信息

在REST系统中，我们可以在不知道之前的信息时，单独解释任何一条信息。

想象一下下面的会话：

非REST

第一个请求获取“todo”的查询结果；第二个请求获取第二页的查询结果；现在想象一下，你只看到了第二条请求，你怎么知道服务器接下来要做什么呢？

在REST中，每条信息都自力更生：

REST

注意每条请求是如何通过自身来解读的。
另一方面，REST客户端和服务器只采用描述里定义的标准操作。对Web来说，这个描述就是 HTTP 。

约束4：通过链接连接资源

你怎么导航到一个你从没有见过的网页？你使用链接！
当你访问一个新页面时，你不需要每次手动地编辑浏览器的地址栏。

在机器接口中，却并不尽然。假设一个应用请求to-do列表。它可能接收如下的描述：

非REST

现在你要如何获取这个列表中的各个项呢？
问得好！我们需要读一下相关的文件。

在REST中，资源彼此间通过超级链接连接在一起：

REST

{
    "name":"My to-dos",
    "items":["/todolists/7/items/35/","/todolists/7/items/36/"]
}

注意你是如何不通过手动的方式知道如何取得列表中的各个项的。其实，你只需要跟随着链接就好了。

遵循这些约束的接口就是REST接口

在你的接口里，遵循这四条约束，你就拥有了一个REST接口

不幸的是，许多自称是“REST”的接口，实际上只是其他的东西（“HTTP接口”），因为它们并不完全遵循所有这些约束。约束2和约束4常常被违反，但也很少见到违反约束1的。对这些开发者来说，“REST”简单地意味着“我们没有XML信息”。

这也是为什么遵循所有这四个约束的REST接口，如今常常被称为“超媒体接口”，这点与第四个约束有关。

REST接口规范

资源URL设计原则

REST风格规定所有资源通过统一资源定位符（URL）定位，资源的RESTful URL采用以下模板：
http(s)://ip:port/(rest)/{service-name}/{version}/{rest-convention}
一个完整URL由服务接口入口、服务接口标识（rest）、服务名称{service-name}、版本号{version}、服务内资源路径{rest-convention}组成，其中服务接口标识"/rest"非规范强制要求

如：获取所有角色基本信息 http://localhost:8086/rest/uam/v1/roles
【规则】若服务接口归属于固定域名，ip:port应该由域名替代。
【规则】URL中字段命名采用英文半角小写字母、数字、中划线或下划线组合，如"search-by-group"，不建议采用驼峰式命名。
【规则】URL长度应小于2083字符，否则服务端返回414状态码
【规则】URL中不能包含URL特殊字符（RFC1738标准），特殊字符需使用特殊字符时需要做URL encode。
【规则】URL中不得包含公司安全红线涉及的敏感信息。
【建议】website暴露给WebUI的RESTful采用模板：
http(s)://ip:port/(rest)/{website-name}/ui/{version}/{rest-convention}
说明：为保持系统对外接口风格一致，在{website-name}和{version}之间添加"ui"标识当前接口为website对外提供的接口。

如何更好的设计RESTful API

一个好的RESTful API，应该具备以下特征：
这个API应该是对浏览器友好的，能够很好地融入Web，而不是与Web格格不入。
1.浏览器是最常见和最通用的REST客户端。好的RESTful API应该能够使用浏览器+HTML完成所有的测试（不需要使用编程语言）。这样的API还可以很方便地使用各种自动化的Web功能测试、性能测试工具来做测试。Web前端应用（基于浏览器的RIA应用、移动App等等）也可以很方便地将多个RESTful API的功能组合起来，建造Mashup类的应用。
这个API中所包含的资源和对于资源的操作，应该是直观和容易理解的，并且符合HTTP协议的要求。
REST开发又被称作“面向资源的开发”，这说明对于资源的抽象，是设计RESTful API的核心内容。RESTful API建模的过程与面向对象建模类似，是以名词为核心的。这些名词就是资源，任何可命名的抽象概念都可以定义为一个资源。而HTTP协议并不是一种传输协议，它实际提供了一个操作资源的统一接口。对于资源的任何操作，都应该映射到HTTP的几个有限的方法（常用的有GET/POST/PUT/DELETE四个方法，还有不常用的PATCH/HEAD/OPTIONS方法）上面。所以RESTful API建模的过程，可以看作是具有统一接口约束的面向对象建模过程。
按照HTTP协议的规定，GET方法是安全且幂等的，POST方法是既不安全也不幂等的（可以用来作为所有写操作的通配方法），PUT、DELETE方法都是不安全但幂等的。将对资源的操作合理映射到这四个方法上面，既不过度使用某个方法（例如过度使用GET方法或POST方法），也不添加过多的操作以至于HTTP的四个方法不够用。
2.如果发现资源上的操作过多，以至于HTTP的方法不够用，应该考虑设计出更多的资源。设计出更多资源（以及相应的URI）对于RESTful API来说并没有什么害处。
这个API应该是松耦合的。
RESTful API的设计包括了三个循序渐进、由低到高的层次：资源抽象、统一接口、超文本驱动。正是这三个层次确保了RESTful API的松耦合性。
3.当设计面向互联网的API时，松耦合变成了一种“必须有”的强需求。紧耦合的API非常脆弱，一旦公布出去，服务器端和客户端都无法持续进化。尤其是服务器端，公布出去的接口根本不敢改，改了之后，几乎所有客户端应用立即无法正常工作。REST这种架构风格就是紧耦合API的解毒剂，这个话题可以谈的很深，这里就不展开了。感兴趣的读者可以参考《REST实战》。
这个API中所使用的表述格式应该是常见的通用格式
在RESTful API中，对于资源的操作，是通过在服务器端-客户端之间传递资源的表述来间接完成的。资源的表述可以有很多种格式，并且在响应和请求中的资源表述格式也会有所不同。GET/POST响应中的资源表述格式，常见的有HTML、XML、JSON；POST/PUT请求中的资源表述格式，常见的有标准的HTML表单参数、XML、JSON。
4.这些常见表述格式，处理起来非常容易，有大量的框架和库提供支持。所以除非有很合理的要求，通常不需要使用自定义的私有格式。
使用HTTP响应状态代码来表达各种出错情况
HTTP响应状态代码，是HTTP协议这个统一接口中用来表达出错情况的标准机制。响应状态代码分成两部分：status code和reason phase。两部分都是可定制的，也可以使用标准的status code，只定制reason phase。
5.如果一个所谓的“RESTful API”对于任何请求都返回200 OK响应，在响应的消息体中返回出错情况信息，这种做法显然不符合“确保操作语义的可见性”这个REST架构风格的基本要求。
这个API应该对于HTTP缓存是友好的
6.充分利用好HTTP缓存是RESTful API可伸缩性的根本。HTTP协议是一个分层的架构，从两端的user agent到origin server之间，可以插入很多中间组件。而在整个HTTP通信链条的很多位置，都可以设置缓存。HTTP协议内建有很好的缓存机制，可以分成过期模型和验证模型两套缓存机制。如果API设计者完全没有考虑过如何利用HTTP缓存，那么这个API的可伸缩性会有很多问题。 关于rest接口设计和rest接口协议的介绍到此就结束了，不知道你从中找到你需要的信息了吗 ？如果你还想了解更多这方面的信息，记得收藏关注本站。 rest接口设计的介绍就聊到这里吧，感谢你花时间阅读本站内容，更多关于rest接口协议、rest接口设计的信息别忘了在本站进行查找喔。

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。