但是,我主要接触的是REST,这是一种基于资源的API和Web服务开发架构风格。在我的职业生涯中有很大一部分时间都参与了构建、设计和使用API 的项目。...但是,我也曾遇到过一些让 REST 蒙羞的 API 例子,错误使用 HTTP 状态码、纯文本响应、不一致的模式、插入端点中动词......因此我决定写篇文章分享一下,在设计 REST API 时的最佳实践。以下是关于设计优秀REST API 的一些建议、提示和指导,帮助您让消费者(以及开发人员)满意。 1....学习 HTTP 基础知识 如果你想构建一个设计良好的REST API,那么你必须了解HTTP协议的基本知识。我坚信这将帮助你做出正确的设计选择。...HTTP 协议提供给 REST API 设计的功能 ,但这些都必须牢记在心里。
序 本文主要研究下rest api的设计。 设计准则 easy to use & hard to misuse 易用不易误用,也就是api设计不要太复杂,要简单易用,而且还不能容易用错。...版本不建议版本化,建议采用新的领域命名才与原有的api区分开来 输出规范 返回码遵循http的返回码规范,4xx表示客户端错误,5xx表示服务端错误。...错误信息格式type表示错误异常类型,code表示错误编号用于个性化错误提示,msg用于错误信息描述,link提供该错误信息的具体描述页面 安全相关 调用方鉴权对于api的消费者,要求调用的时候强制提供...服务质量保障 提供SLA 提供流量管理、熔断、限流 提供服务扩容机制 提供故障演练 提供审计功能 监控异常流量 提供调用方间的隔离 小结 rest api的设计牵扯的方面比较多,本文暂时只是先列了一些...doc API设计要点 聊聊jpa的动态查询 使用RSQL实现端到端的动态查询
Flink REST API 介绍Flink REST API 是 JobManager 提供的 HTTP 接口,用户可以通过 GET、POST 等 REST 定义的方法,请求获取作业、JobManager...非阻塞的 Flink REST API 设计要点关于拓展 Flink REST API 的方法,我们可以在 Flink 官网文档、各类技术社区文章中得到详细的指引,因而这里不再赘述基础的细节,而是更侧重于讲解遇到的一些常见的问题和解决方案...→ TaskManager → 用户定义的 Task请求体、返回体设计通常对于接受 GET 方法的 REST API 而言,可以直接使用 EmptyRequestBody 类作为请求体的结构,方便快捷...REST Handler 设计handler 是一个 REST API 接口的执行者,我们可以通过实现 handleRequest 方法来定义请求的处理逻辑。...API 很简单;但是如果设计不当,阻塞了 Flink 的核心流程,会造成作业不稳定甚至多组件超时退出的后果。
REST端点用于集成应用程序或服务器端向客户端提供服务。在本文中,将介绍基于CRUD的SpringBoot来设计和实现REST端点。...设计和实施端点 端点应简短易用。例如,为了通过Id获取客户,我们可以使用/ customers / {id}这样的端点。...所有这些方法都有助于设计简单的REST端点,因为这是标准的,所以每个人都可以理解它们。 GET GET方法用于访问资源。要根据ID获取客户记录,我们可以使用/ customers / {id}等端点。...当客户端请求无效或不存在的“id”时,我们可以使用标准HTTP响应代码,而不是使用自定义正文或错误消息进行响应。HTTP响应代码是REST中用于通知处理状态的标准方式。...有许多类别的代码可用,这里是关于这些代码的一些信息的链接。 404 - 未找到:如果数据存储中没有“id”,则使用此HTTP代码是合适的。
我们经常见到,程序开发可能只用了半个月,但是接口的联调却经常需要花费半个月甚至一个月左右。 如果API的设计更规范更合理,在很大程度上能够提高联调的效率,降低沟通成本。那么什么是好的API设计?...另外,REST API的书籍很多,但是完整完善实践丰富的设计指导并不多见,我们有幸看到了微软团队的作品——Microsoft REST API Guidelines,因此才有了此篇内容。...翻译的不对之处,请多多指教。 什么是REST API?...Rest不是一种协议,也不是一种文字格式,更不是一种开发框架,它是一种系列的设计约束的集合:无状态性、将超媒体作为应用状态的引擎,这个约束我们统称Fielding约束。...那么满足这些约束条件和原则的应用程序或设计就是 RESTful。 为什么用REST API? 1.前后端分离主要以API为界做接洽的,这样就会有很多的API,API的表现力更强,更加便于理解。
所有章节我们翻译校对完成后,将会将最终定稿签入到我们的Github开源库托管,方便大家查阅和校正。同时,我们推荐将此规范作为团队的REST API设计指导和规范。...因此,这些准则的一个目标是确保任何支持基本 HTTP 协议的客户端都可以简单且一致地使用 Microsoft REST API。...一致性的好处在于可以不断地积累合理的规范;一致性使团队拥有统一的代码、模式、文档风格和设计策略。...允许Service服务开发人员利用其他Service服务的基础来开发一致的 REST API 节点。 允许合作伙伴 (如非微软团队) 使用这些准则来设计自己的 REST API。...本文档中使用的“REST”术语代指具有 RESTful风格的服务,而不是仅仅遵循 REST。
1 简介 REST API 安全设计指南。...REST 全称是 Representational State Transfer,它利用传统 Web 特点,提出一个既适于客户端应用又适于服务端的应用的、统一架构,极大程度上统一及简化了网站架构设计。...目前,在三种主流的 Web 服务实现方案中,REST 模式服务相比复杂的 SOAP 和 XML-RPC 来讲,更加简洁。...越来越多的 web 服务使用 REST 设计并实现,但是它缺少安全特性。 REST 全称是 Representational State Transfer,即表述性无状态传输。...这样的设计就防止了数据被篡改。通过这种 API Key 的设计方式加了时间戳防止部分重放,加了校验,防止数据被篡改,同时避免了传输用户名和密码,当然也会有一定的开销。
REST API 安全设计指南。...目前在三种主流的Web服务实现方案中,REST模式服务相比复杂的SOAP和XML-RPC对比来讲,更加简洁,越来越多的web服务开始使用REST设计并实现。...但其缺少安全特性,《REST API 安全设计指南》就是一个REST API安全设计的指南,权当抛砖引玉,推荐网站后台设计及网站架构师们阅读。...rest_api是从url获取的为/rest/v1/interface/eth0,最后计算sign值,完之后和url中的sign值做校验。...这样的设计就防止了数据被篡改。 通过这种API Key的设计方式加了时间戳防止了部分重放,加了校验,防止了数据被篡改,同时避免了传输用户名和密码,当然了也会有一定的开销。
前言 前面我们说了,如果API的设计更规范更合理,在很大程度上能够提高联调的效率,降低沟通成本。那么什么是好的API设计?这里我们不得不提到REST API。...关于REST API的书籍很多,但是完整完善实践丰富的设计指导并不多见,我们有幸看到了微软团队的作品——Microsoft REST API Guidelines,因此才有了此篇内容。...上篇内容: REST API设计指导——译自Microsoft REST API Guidelines(三) 6 Client guidance 客户指导 To ensure the best possible...PS:国内使用这种设计模式的比较少见,更倾向于是一些更通用的API使用这种模式。...表的请求头应该遵循微软REST API服务规范。使用这些标头不是必须的,但是如果用到,那么它们必须使用一致。
前面我们说了,如果API的设计更规范更合理,在很大程度上能够提高联调的效率,降低沟通成本。那么什么是好的API设计?这里我们不得不提到REST API。...关于REST API的书籍很多,但是完整完善实践丰富的设计指导并不多见,我们有幸看到了微软团队的作品——Microsoft REST API Guidelines,因此才有了此篇内容。...Microsoft REST API 准则基本要求的一方面就是 服务的分类必须符合以下定义。...错误不会影响整体 API 的可用性。 译者注:错误可以理解成客户端参数错误,通常返回“4XX”状态码,并不影响整体的API使用。...延迟定义为具体 API 被调用完成所需的时长, 尽可能使用客户端调用进行测量。
前言 Yarn Rest Api 返回的数据都是XML格式,需要解析XML。...每秒消耗的内存总和 vcoreSecond string 所有的container每秒消耗的核心数总和 queueUsagePercentage double 所属队列的资源使用百分比 clusterUsagePercentage...double 所属集群的资源使用百分比 logAggregationStatus string 日志聚合状态 unmanagedApplication boolean 未被管理的应用程序 查询单个任务...appsCompleted int 完成的应用程序数量 appsPending int 等待的应用程序数量 appsRunning int 正在运行的应用程序数量 appsFailed int 失败的应用程序数量...appsKilled int 被杀死的应用程序数量 reservedMB long 保留的内存量(MB) availableMB long 可用的内存量(MB) allocatedMB long 分配的内存量
在了解 REST API URI 设计的规则之前,让我们快速过一下我们将要讨论的一些术语。 URI REST API 使用统一资源标识符(URI)来寻址资源。...在今天的网站上,URI 设计范围从可以清楚地传达API的资源模型,如: http://api.example.com/louvre/leonardo-da-vinci/mona-lisa 到那些难以让人理解的...REST API 设计人员应该创建 URI,将 REST API 的资源模型传达给潜在的客户端开发人员。在这篇文章中,我将尝试为 REST API URsI 引入一套设计规则。...应鼓励 REST API 客户端使用 HTTP 提供的格式选择机制,即请求 header 中的 Accept 属性。...结论 当你设计 REST API 服务时,你必须注意资源,这些资源由 URI 定义。 你正在构建的服务中的每个资源,都将至少有一个 URI 来标识它。这个 URI 最好是有意义的,并能充分描述资源。
这是一个完整的图表,可以轻松理解 REST API 的原理、方法和最佳实践。 现在,让我们从每个盒子的原理开始详细说明它。...最佳实践 现在,让我们换个角度来了解 REST 的基本最佳实践,这是每个工程师都应该知道的。 保持简单和细粒度:创建模拟系统底层应用程序域或系统数据库架构的 API。...资源命名:当资源命名正确时,API 是直观且易于使用的。做得不好,同样的 API 会让人感觉很笨拙,并且难以使用和理解。RESTful API 适用于消费者。...为您的客户设计,而不是为您的数据设计。 - 复数:普遍接受的做法是始终在节点名称中使用复数形式,以保持您的 API URI 在所有 HTTP 方法中保持一致。...本文 https://jiagoushi.pro/principles-best-practices-rest-api-design 讨论:知识星球【首席架构师圈】或者加微信小号【cea_csa_cto
基于REST API的项目返回的数据结构题都是统一的,这样方便接口对接和使用。...因此,对结果对象的设计会有一定的要求: 一个结果对象要能够同时支持成功和失败的数据结构; 要能够处理多种类的返回结果对象; 能够很轻易的判断出结果是成功还是失败; 能够存储错误编码和错误信息; 下面就基于...Spring Boot项目来设计一下对应的统一结果返回对象。...比如,在发生错误时,可能不希望data为null,如果使用的是Spring Boot框架,可以通过如下方式进行配置: spring.jackson.default-property-inclusion=...NON_NULL 如果使用的是Java 8或Gauva,想要要排除可选类型,则应使用NON_ABSENT值。
本章介绍如何使用 %REST.API 类来创建、更新和删除 REST 服务。...使用 %REST.API 类创建或更新 REST 服务创建 REST 服务的推荐方法是从 REST 服务的 OpenAPI 2.0 规范开始,并使用它来生成 REST 服务类。...要使用 %REST.API 类执行此操作:获取 REST 服务的 OpenAPI 2.0 规范,采用 JSON 格式,并将规范保存为文件。该文件必须是 UTF-8 编码的。...在要定义 REST 服务的命名空间中,使用该文件创建 %DynamicObject 的实例。然后调用 %REST.API 类的 CreateApplication() 方法。...使用 %REST.API 类删除 REST 服务要使用 %REST.API 类删除 REST 服务:在可以找到 REST 服务的命名空间中,调用 %REST.API 类的 DeleteApplication
Burp 可以测试任何 REST API 端点,前提是您可以为该端点使用普通客户端来生成正常流量。流程是通过 Burp 代理客户端的流量,然后用正常的方式进行测试。...除非 API 使用 Swagger 文件,否则不使用普通客户端就无法完全自动化,因为 REST API 端点没有标准格式来定义可以向它们发出的请求(就像 SOAP 那样通过 WSDL 文件的端点)。...因此,没有办法绕过使用真实客户端生成示例流量的需要。 在某些情况下,您可以使用浏览器访问 API,但这并不总是可行的。...在本教程中,我们将演示如何使用移动设备通过 Burp Suite 代理 API 流量。 您可以使用此方法映射整个 API,或定位和测试特定操作。...image.png 使用通过 Burp Proxy 工作的移动应用程序,通过以下链接手动映射应用程序、提交表单并逐步完成多步骤流程。此过程将使用请求的所有内容填充代理历史记录和目标站点地图。
了解应用于 REST 之上的 HTTP 知识 如果你想要构建设计优良的 REST API,了解一些关于 HTTP 协议的基础知识是很有帮助的,毕竟磨刀不误砍材工。...但是,就 REST API 设计本身而言,所涉及到的 HTTP 知识要点大概包含以下几条: HTTP 中包含动词(或方法): GET、POST、PUT、PATCH 还有 DELETE 是最常用的。...当然了,你可以将 HTTP 协议中所提供的任何东西应用于 REST API 的设计之中,但以上这些是比较基础的,因此时刻将它们记在脑海中是很有必要的。 2....避免在 URI 中使用动词 如果你理解了第 1 条最佳实践所传达的意思,那么你现在就会明白不要将动词放入 REST API 的 URI 中。...在 NodeJS 中,Restify 似乎也是一个不错的选择,尽管我还没有尝试过。我强烈建议你给这些框架一个机会!它们将帮助你构建规范,优雅且设计良好的 REST API 服务。
在了解REST API URI设计的规则之前,让我们快速浏览一些我们将要讨论的术语。 URIs REST API使用统一资源标识符(URI)来寻址资源。...REST API设计人员应该在考虑将REST API资源模型传达给潜在的客户端开发者的前提下,创造URI。在这篇文章中,我将尝试为REST API URI 引入一套设计规则。...应鼓励REST API客户端使用HTTP提供的格式选择机制Accept request header。 为了是链接和调试更简单,REST API应该支持通过查询参数来支持媒体类型的选择。...结论 当你在设计REST API服务时,您必须注意这些由URI定义的资源。 正在构建的服务中的每个资源将至少有一个URI标识它。这个URI最好是有意义的,且能充分描述资源。...URI的名称和结构应该能够向使用者传达更清晰的含义。通过遵循上述规则,您将创建一个更清晰的的REST API与更友好的客户端。这些并不是REST的规则或约束,仅仅是API的增强和补充。
使用 pyhttptest 轻松测试 REST API 现在,我们每个人都面临着 REST API,要么开发这样的服务,要么使用这样的服务。...这些服务大多遵循 RESTful 原则,并使用 JSON 格式进行通信,由于其简单性,JSON 格式成为最广泛使用的格式。...pyhttptest 命令行工具,用于通过 RESTful api 进行 HTTP 测试。...这个工具通过简单的三个步骤自动化测试 安装 pip install pyhttptest 用文件中最简单且广泛使用的格式 JSON 描述针对 API 服务的 HTTP 请求测试用例 发送 HTTP GET...为了不搞乱这些测试并打破常规,我建议在您的项目根目录中创建一个名为live_tests/ 。 在新目录中,可以将所有json文件,定义了 API 测试用例的文件。 通过这样做,您的测试将很容易区分。
现在,我们每个人都面临着 REST API,要么开发这样的服务,要么使用这样的服务。 此外,我们正处于微服务的时尚时代,我们将业务逻辑分割成独立于每个服务的小型独立服务。...这些服务大多遵循 RESTful 原则,并使用 JSON 格式进行通信,由于其简单性,JSON 格式成为最广泛使用的格式。...pyhttptest 命令行工具,用于通过 RESTful api 进行 HTTP 测试。...这个工具通过简单的三个步骤自动化测试 安装 pip install pyhttptest 用文件中最简单且广泛使用的格式 JSON 描述针对 API 服务的 HTTP 请求测试用例 发送 HTTP...为了不搞乱这些测试并打破常规,我建议在您的项目根目录中创建一个名为live_tests/ 。 在新目录中,可以将所有json文件,定义了 API 测试用例的文件。 通过这样做,您的测试将很容易区分。
领取专属 10元无门槛券
手把手带您无忧上云