REST API设计中,响应是否应该包含输入参数以供参考取决于具体的设计需求和业务场景。一般来说,REST API的响应应该包含足够的信息,以便客户端能够理解请求的结果和可能的错误情况。
包含输入参数的优势在于:
然而,也有一些情况下不建议将输入参数包含在响应中:
综上所述,是否将输入参数包含在REST API的响应中应该根据具体情况进行权衡和决策。在设计过程中,需要考虑到安全性、可用性、易用性等因素,并根据实际需求来确定是否包含输入参数。
主要包含两个方面的规范:API 本身的设计规范、API 帮助文档的编写规范。 1.2. 参考资料 《Representational State Transfer (REST)》 1.3....Ø REST:一种开放的基于互联网的软件架构模式。参见:《Representational State Transfer (REST)》。 2. API 设计规范 2.1....主体输入 考虑到接口的扩展性,所有API的输入只能接受一般的 JSON 对象作为输入参数,同时也只能输出一个 JSON 对象。 当输入输出的值是单一值、数组时,需要使用一个对象对其进行封装。...API操作设计 每个具体的 API地址,都是一个操作。操作分为两种类型:资源型操作、业务型操作。 2.3.1. 资源型操作 资源型操作是满足REST规范化设计的。在设计API 时,应尽量首选这种模式。...o URI 参数:如果 URI 中某部分是动态的,请使用大括号说明:api/values/{id}。 o URI 查询参数:如果 URI 地址有参数,描述各项参数与说明。每个参数是否可选。
全面系统的测试是必不可少的。Java 程 序员常常借助于 JUnit 来测试自己的 REST API,不,应该这样说,Java 程序员常常借助于JUnit 来测试 REST API的实现!...是一种专为测试 REST API 而设计的 DSL。...显然,我的cookie并不包含登陆信息,因为我压根就没有登陆,当然这是网站的设计,与rest-assured无关。...(none)以及URL编码(true),通过下面的方法重置:七、specification在不同的测试用例当中,我们可能会有重复的响应断言或者是请求参数,那么我们可以将重复的这一部分提取出来定义一个规范或者模板...ResponseSpecification重用例如,你想在多个测试用例中,都使用这样的断言:判断响应状态码是否为200,并且Json数组"x.y"的大小是否 等于2。
总结一下就6个方面: 用户 能做什么 如何做 - 分解步骤 输入 输出 目标 避免从开发者角度设计API 这部分包含几个方面....使用OAS来描述REST API的资源以及Action 创建OAS文档 建立一个products.yaml文件. 然后在里面输入 api 或 open等字符串, 会出现两个提示选项: ?...第5行 paths, paths属性应该包含该API可用的资源. 这里面使用 {} 仅仅是为了让文档验证通过, 因为我目前还没有写什么内容....每个响应都以状态码进行标识, 并且必须包含一个description属性. 注意: 状态码数字必须用双引号括起来, 因为它的类型本应该是字符串, 而这里的200是一个数字....那么使用JSON Schema来描述它就应该是这样的: ? 还没完, 我还必须指出属性是否是必填的, 然后我再加上一个remark属性, 它不是必填的: ?
但是,我主要接触的是REST,这是一种基于资源的API和Web服务开发架构风格。在我的职业生涯中有很大一部分时间都参与了构建、设计和使用API 的项目。...因此我决定写篇文章分享一下,在设计 REST API 时的最佳实践。以下是关于设计优秀REST API 的一些建议、提示和指导,帮助您让消费者(以及开发人员)满意。 1....学习 HTTP 基础知识 如果你想构建一个设计良好的REST API,那么你必须了解HTTP协议的基本知识。我坚信这将帮助你做出正确的设计选择。...Mozilla Developer Network文档上关于HTTP概述是一个相当全面的参考资料,尽管如此,在REST API设计方面,以下是将HTTP应用于RESTful设计的简要说明: HTTP具有动词...不要返回纯文本 尽管并非强制规定的,但大多数REST API通常约定使用JSON作为数据格式。然而,仅返回包含JSON格式字符串的响应体是不够好的。您还应该指定Content-Type标头。
这些系统按照自己的理解,采用了类似REST API的部分形式(如用GET/POST/PUT/DELETE进行CURD),但更多的是随意设计,搞出了REST-RPC式,甚至是RPC式的API。...2) 状态转移 状态其实应该分为应用状态和资源状态。 应用状态由客户端保存维护,例如会话状态等。客户端通过REST API返回的表述,以及表述中的URI,进行客户端应用状态的转移。...因此,需要明确地定位一个资源,而URI技术正好满足这个需求,所以REST中通过URI来定位资源。 资源是一个对象,所以URI中一般只能包含名词(一般是复数),不应该包含动词。...但是否使用了GET/POST/PUT/DELETE,并不能作为评判一个系统是否符合REST架构风格的标准。...既减少了私有协议的兼容性问题,又能作为标准适用于所有的RESTful架构。 5) 返回内容 REST API的返回内容应该是资源的表述。
相比之下,我们应该改用“HTTP API”和“hypermedia API”这两个说法,使用它们可以更好地区分两种不同的 Web 服务编程接口设计。...可以引入专业的中间服务器来处理响应缓存,从而让这一跨域问题与终端服务器上的业务逻辑分离开。 此外,REST 风格鼓励服务器向客户端发出指示,告知后者是否可以在本地缓存资源。...由于客户端应用程序不会被写入静态接口,因此 API 本身可以自由地动态更改形态,以响应用户输入、算法甚至是人工智能。而且,设计渐进式发展的 API(与重大更改和版本控制相关的问题更少)会容易很多。...那为什么我们要谈论 RESTful API 呢? 我们今天所说的“REST API”应该重新分类为“HTTP API”或“hypermedia API”。 HTTP API 是围绕 HTTP 设计的。...至于 REST,在计算机科学领域,这应该被视为一个相当特殊的概念。它的设计用例确实非常狭窄。 REST 适用于跨越多个组织的基于网络的长周期应用程序。
Level 3:API基于HATEOAS原则设计,简单地说就是响应消息中包含后续操作的URI资源,Level 3拥有协议自描述功能。...● class,具体调用方法的URL,参考下文的接口列表。● params,公共请求参数,参考下文的请求参数。...● URL内参数中包含可变字段,如/orders/orderid,orderid为URL内参数,需要对应填值,具体参考下文的接口列表。...● 对于POST请求参数,传递的参数必须使用JSON格式,公共请求参数仍置于URL中,具体方式可参考下文的代码示例。...【返回结果】 API接口使用标准HTTP返回码,只有2XX才是正确返回,下面是可能的返回码汇总: ● 200,请求成功,具体请求结果参考响应内容JSON值。
REST允许通过简单的URL(而不是复杂的请求主体或POST参数)与基于web的系统交互。...服务器不应该猜测Content-Type 它应该总是检查Content-Type头和内容是否是相同的类型。...(3)XML编码 XML绝不应该由字符串连接构建。 它应该始终使用XML序列化器构造。 这确保发送到浏览器的XML内容是可解析的,并且不包含XML注入。...当设计REST API时,不要只使用200成功或404错误。 以下是每个REST API状态返回代码要考虑的一些指南。 正确的错误处理可以帮助验证传入的请求,并更好地识别潜在的安全风险。...一些方法(例如,HEAD,GET,OPTIONS和TRACE)被定义为安全的,这意味着它们仅用于信息检索,并且不应该更改服务器的状态。在设计和构建REST API时,您必须注意安全方面。
主体包含客户端想要传输到服务器的数据,例如请求的有效负载。 GraphQL API GraphQL 是一种用于 API 的查询语言,也是使用现有数据完成这些查询的运行时。...同样,将数据提供给客户端的方式是 GraphQL 和 REST 分歧最大的地方。在 REST 设计中,客户端提交 HTTP 请求,数据作为 HTTP 响应返回。...GraphQL 的安全控制不如 REST API 中的安全控制发达。为了利用 GraphQL 中的数据验证等当前功能,开发人员必须设计新的身份验证和授权技术。...与 REST API 相比,这是一个明显的区别,在 REST API 中,每个 状态代码都指向某种类型的响应。...GraphQL 中的任何合法答案都应该是 200,包括数据和错误响应。客户端工具将有助于更有效地管理错误。错误作为特定错误对象下的响应主体的一部分进行处理
REST 定义了四个接口约束:资源的识别、通过表示的资源操作、自描述消息和作为应用程序状态引擎的超媒体。 自描述消息:每条消息都包含足够的信息来描述如何处理消息。...超媒体作为应用程序状态引擎 (HATEOAS):客户端通过正文内容、查询字符串参数、请求标头和请求的 URI(资源名称)传递状态。服务通过正文内容、响应代码和响应头向客户端提供状态。...最佳实践 现在,让我们换个角度来了解 REST 的基本最佳实践,这是每个工程师都应该知道的。 保持简单和细粒度:创建模拟系统底层应用程序域或系统数据库架构的 API。...此外,我们可能希望指定要包含在响应中的资源的字段或属性,从而限制返回的数据量。我们最终想要查询特定值并对返回的数据进行排序。 版本控制:有很多方法可以破坏合同并对 API 开发中的客户产生负面影响。...为您的客户设计,而不是为您的数据设计。 - 复数:普遍接受的做法是始终在节点名称中使用复数形式,以保持您的 API URI 在所有 HTTP 方法中保持一致。
总结 1.概览 本文将重点介绍如何在Spring中添加ETag功能、如何使用 curl来验证添加了ETag功能的REST API以及对这些REST API进行集成测试。...2.REST和 ETag 来自Spring官方文档中对ETag特性的描述: ETag(实体标签)是由符合HTTP/1.1的Web服务器返回的HTTP响应头,用于检查给定URL的返回值是否发生变化。...API请求时,会使用If-None-Match头携带上一步保存的ETag值;如果服务器上的资源没有发生变化,那么响应将不会包含任何响应体,并且返回的HTTP状态码将会是304——Not Modified...;请记住,自从上次检索以来,资源已经被更新了,所以前面存储的ETag值已经不能代表现在的资源了——响应将包含新的数据和一个新的ETag,这个新的ETag可以被存储起来以供后续使用: curl -H "Accept...5.测试ETag 那就开始吧——在检索一个资源时,我们需要验证返回的响应体将包含一个“ETag”头。
REST作为API设计的基础 有些人可能会强烈反对反对提到的/ translate和其他JSON路由是API路由。其他人可能会同意,但也会认为它们是一个设计糟糕的API。...Fielding和其他REST纯粹主义者对评判一个API是否是REST API有严格的规定,但软件行业在实际使用中引用REST是很常见的。...因为这个原则需要服务器和客户端之间就可以客户端能够运行您可能会认为服务器可能会返回JavaScript代码以供Web浏览器客户端执行,但REST非专门针对Web浏览器客户端而设计。...正如我上面提到的那样,email字段需要特殊处理,因为我只想在用户请求自己的数据时才包含电子邮件。我所以使用include_email标志来确定该级别是否包含在表示中。...我为这个请求返回的响应将是新用户的表示,因此使用产生to_dict()它的有效格式。创建资源的POST请求的响应状态代码应该是201,即创建新实体时使用的代码。
(HATEOAS) RESTful使用应该注意的问题 版本(Versioning) 参数命名规范 url命名规范 统一返回数据格式 http状态码 合理使用query parameter 多表、多参数连接查询如何设计...URL API请求授权 1.REST的来源 REST:Representational State Transfer(表象层状态转变),如果没听说过REST,你一定以为是rest这个单词,刚开始我也是这样认为的...请求所需的一些信息都包含在URL的查询参数、header、body,服务端能够根据请求的各种参数,无需保存客户端的状态,将响应正确返回给客户端。无状态的特征大大提高的服务端的健壮性和可拓展性。...统一返回数据格式 对于合法的请求应该统一返回数据格式,这里演示的是json code——包含一个整数类型的HTTP响应状态码。...多表、多参数连接查询如何设计URL 这是一个比较头痛的问题,在做单个实体的查询比较容易和规范操作,但是在实际的API并不是这么简单而已,这其中常常会设计到多表连接、多条件筛选、排序等。
在我看来,所有的 API 都应该可以在不看注释和说明的情况下被调用方理解,从调用端点,到参数,和 JSON 的键。 这儿,我参考了国外的一些规则。规则也很简单: 用名词,别用动词。...保持响应的一致 一致性是好的 API 的优秀品质。开发中,我们应该在各种方面做到一致,包括命名、URI、请求、响应等。而在这里面,响应的一致性是我对团人的一个硬性要求。 API 是要让别人去调用的。...每个代码都有独特的含义,应该在独特的场景中使用。这个内容网上有很多,我就简单列一下: 1xx - 信息性响应代码,简单说就是一个状态通知。 2xx - 成功响应代码。所有的成功都会在这个范围。...拿上面的例子来说,GET /client/23,取 clientId = 23 的数据,我们需要做以下的工作: 检查请求是否有 clientId 参数,如果没有,应该是一个 400 的状态 检查传入的...而且,除了状态码外,还要返回相应的错误消息,例如:输入参数 clientId 没有输入、ID 为 23 的数据记录不存在,等等。
在论文中,他提出了客户端和服务器之间应该分开的六项原则;客户端和服务器之间的通信应该是无状态的;它们之间可以存在多个层次结构;服务器响应必须声明为可缓存或不可缓存;其接口的统一性必须基于客户端、服务器和中间组件之间的所有交互...Swagger 是用于创建交互式 REST API 文档的规范和框架。它使文档能够与对 REST 服务所做的任何更改保持同步。它还提供了一组工具和 SDK 生成器,用于生成 API 客户端代码。...参数 Java @Annotations 除了身份验证和授权之外,构建安全 Web 服务的一个重要领域是确保输入始终得到验证。Java Bean 注解提供了实现输入验证的机制。...我们可以通过@Valid在方法参数中使用注解来实现。 我们的类应该在处理软删除之前验证传入的标识符请求。...@RequestBodyannotation 表示方法参数应该绑定到 Web 请求的正文,而@ResponseBody表示方法返回值应该绑定到 Web 响应正文。
在URI定义好以后,还有详细的参数定义,包括类型以及是否必选。 响应消息 有多种方式,XML,JSON。XML有XSD作为参考。...这类设计如果滥用get去处理其他类型的操作,那么和2无异。 REST风格非REST思想:资源URI定义+参数(包含操作方法名)。其实就是RPC的REST跟风。...响应消息设计 REST标准方式,将Resource State传输返回给客户端,Http消息作为应用协议而非传输协议 以XML作为消息承载体,Http作为消息传输协议,处理状态自包含。...其实我和他的感觉是一样的,REST是否真的在我们现有的服务框架中需要集成,理解了REST的思想再去看应用场景,那么可以发现如果要完全遵循REST的设计理念来设计接口的话,那么强要去改变现有已经存在的或者还未开发的接口就会落入为了技术而技术...我们将会和我们的兄弟公司合作,也会参考他们的设计理念,在参考当前各个网站的实现情况下,部分的采用这类形式的发布,提供给第三方的ISV,无疑是我现在把REST融入到ASF中最好的理由。
引言 Web API 已经在最近几年变成重要的话题,一个干净的 API 设计对于后端系统是非常重要的。...本篇文章是结合我最近的一个项目,基于koa+mongodb+jwt来给大家讲述一下 RESTful API 的最佳实践。 RESTful API 是什么?...分层系统(Layered System) 按需代码(Code-On-Demand) 看完了 REST 的六个约束,下面让我们来看一下行业内对于RESTful API设计最佳实践的总结。...API 应该提供参数,过滤返回结果。下面是一些常见的参数(包括上面的查询、分页以及字段过滤): ?limit=10:指定返回记录的数量 ?offset=10:指定返回记录的开始位置。 ?...具体使用方式可以参考https://www.npmjs.com/package/jsonwebtoken 实战 初始化项目 mkdir rest_node_api # 创建文件目录 cd rest_node_api
2.png 它包含三个层级: API(输入)模块:这一层将系统与外界连接起来。此处实现了 HTTP REST、GraphQL、Web Sockets 等协议 —— 无论需要什么,都有!...这些服务对调用者(我猜,我们可以更类似地命名它们)进行配置,并将它们提供给 Flows。每个服务都可能会包含提供给调用者的参数,以便它与后端服务进行通信。...这其中包括从其他调用传递的请求和响应参数、关于如何调用服务的细节、超时信息等。为了获得更大的灵活性,我们在请求参数中加入了基于 Mustache 的模板引擎。...从根本上来说,中间件其实是一个可以重复使用的同步调用,能使所有需要它们的流都可以使用一些常见任务。例如,检查处理非公开信息的所有 Flows 是否需要包含有效令牌。...(是的,我知道仅抓取请求的数据会更有效率,但这只是一个简单的例子。我想不出更合理的东西了。)。 当 Flow 完成时,其输出被 API 接收。然后,它们被用于为其实现的协议创建适当的响应格式。
关于 restful api 本身以及设计原则,我陆陆续续也看过很多的文章和书籍,在读过原文后,感觉文中指出的 13 点最佳实践还是比较全面的且具有参考意义的,因此翻译出来分享给大家。...但是,就 REST API 设计本身而言,所涉及到的 HTTP 知识要点大概包含以下几条: HTTP 中包含动词(或方法): GET、POST、PUT、PATCH 还有 DELETE 是最常用的。...当然可以,不过让我讲一个故事: 我曾经使用过一个 API,对于它返回的所有响应的状态码均是 200 OK,同时通过响应数据中的 status 字段来表示当前的请求是否成功,比如: {...优雅地处理尾部斜杠 一个好的 URI 中是否应当包含尾部斜杠,并不具有探讨价值,选择一种更倾向的风格并保持一致性即可,同时当客户端误用尾部斜杠时,提供重定向响应。 我再来讲我自己的一个故事。...在 NodeJS 中,Restify 似乎也是一个不错的选择,尽管我还没有尝试过。我强烈建议你给这些框架一个机会!它们将帮助你构建规范,优雅且设计良好的 REST API 服务。
在参考了GitHub API设计和大量博客文章后总结了一下RESTful API的设计,分享如下。...由于他是HTTP协议(1.0版和1.1版)的主要设计者、Apache服务器软件的作者之一、Apache基金会的第一任主席,所以REST原则迅速流行起来。...基本两种方法: ETag:当生成请求的时候,在HTTP头里面加入ETag,其中包含请求的校验和和哈希值,这个值和在输入变化的时候也应该变化。...如果输入的HTTP请求包含IF-NONE-MATCH头以及一个ETag值,那么API应该返回304 not modified状态码,而不是常规的输出结果。...API应该提供参数,过滤返回结果。 下面是一些常见的参数: ?limit=10:指定返回记录的数量 ?offset=10:指定返回记录的开始位置。 ?
领取专属 10元无门槛券
手把手带您无忧上云