, 4xx 表示客户端错误 和5xx 表示服务器错误 当然你还可以使用其他 HTTP 协议提供给 REST API 设计的功能 ，但这些都必须牢记在心里。...于是，我开始使用： POST: /buckets/ 然后一切都顺利进行了。API没有修复，但希望您可以防止消费者遇到此类问题。...如果资源以某种方式已经存在，但这不应被视为错误。 13. 使用专门针对REST API的网络框架 作为最后一个最佳实践，让我们讨论这个问题：如何在您的API中实际应用最佳实践？...各种语言中已经出现了新框架, 它们专门用于构建REST APIs。它们能够帮助您轻松遵循最佳做法，并提高生产力。 在Python中, 我找到过其中之一优秀API框架就是Falcon。...在Node中，Restify似乎也是一个很好的选择，尽管我还没有尝试过。我强烈建议您试一试这些框架，它们将帮助您构建美观、优雅且设计精良的REST API。
不要返回纯文本 虽然返回 JSON 数据格式的数据不是 REST 架构规范强制限定的，但大多 REST API 都遵循这条准则。...避免在 URI 中使用动词 如果你理解了第 1 条最佳实践所传达的意思，那么你现在就会明白不要将动词放入 REST API 的 URI 中。...某天，我在将某个 API 端点集成到项目中，但是我总是收到 500 Internal Error 的错误，我调用的端点差不多看起来这样： POST: /entities ``` 调试一段时间之后...在各种语言中，许多专门用于构建 REST API 服务的新框架已经出现了，它们可以帮助你在不牺牲生产力的情况下，轻松地完成工作，同时遵循最佳实践。...在 NodeJS 中，Restify 似乎也是一个不错的选择，尽管我还没有尝试过。我强烈建议你给这些框架一个机会！它们将帮助你构建规范，优雅且设计良好的 REST API 服务。
这些系统按照自己的理解，采用了类似REST API的部分形式（如用GET/POST/PUT/DELETE进行CURD），但更多的是随意设计，搞出了REST-RPC式，甚至是RPC式的API。...客户端通过REST API返回的表述，以及表述中的URI，进行客户端应用状态的转移。 但REST更强调的是资源状态。...例如，有些系统所有接口都使用GET和POST方法，如果该系统只提供查询和创建操作，那么可能是符合REST架构风格的；但如果该系统还提供修改、删除操作，则该系统不符合REST架构风格。...302（Moved Temporarily）：表示资源的URI已临时性更改，需要在响应内容中获取新的URI。 400（Bad Request）：表示请求有问题，如参数错误等。...500（Internal Server Error）：通用内部错误。 502（Bad Gateway）：网关错误，从上游服务器收到无效响应。
正如我们在 POST 部分中讨论的那样，通常不会出现这种情况。但是如果客户端能够控制服务器端信息空间，那么这种操作也是合理的。...DELETE 请求意在实现等幂。可能由于网络故障 DELETE 请求被打断，这时我们希望客户端继续尝试。第一次请求无论成功与否，资源都应该返回204（无指定内容）。...表1 成功的客户端请求 ? 表2 — 客户端重定向请求 表 3 中的响应代码表示客户端请求无效，如果条件不发生变化，重新请求仍无法处理。这些故障可能有请求格式错误、未授权的请求、请求的资源不存在等。...表3 客户端请求错误 最后，表4中的响应代码表示服务器暂时无法处理客户端请求（可能仍然无效）。客户端应当在将来的某个时候重新请求。 ?...表4 服务器处理请求错误 服务根据其自身功能要求具有不同程度的可扩展性。 注意：试试响应代码 418，它会返回简洁有力的回复："我是一个茶壶。"
REST API 关于什么是REST，我就不在这里赘述了，直接推荐REST作者的经典论文： 架构风格与基于网络的软件架构设计(中文修订版) 下面我只想用一些实例描述几种架构风格在API定义方面的不同。...至于这个问题的答案，我就不再展开了。 API定义 本项目的API是打算使用REST方式定义的。那么，首先，就是资源的Endpoint定义。...: 描述信息，成功时为”success”，错误时则是错误信息 data: 成功时返回的数据，类型为对象或数组 之前，我是喜欢将请求状态码和业务错误码分开处理的。...因此，这里的code我之前喜欢将其定义为业务错误码。但是，如果按照REST风格来设计，还是有统一的code更合适。因此，我这次尝试下改变习惯。...因此，我将采用的方案是：在客户端自己生成nonce，但服务端不保存nonce，只要检查请求中是否存在nonce即可。
正如我们在 POST 部分中讨论的那样，通常不会出现这种情况。但是如果客户端能够控制服务器端信息空间，那么这种操作也是合理的。...DELETE 请求意在实现等幂。可能由于网络故障 DELETE 请求被打断，这时我们希望客户端继续尝试。第一次请求无论成功与否，资源都应该返回204（无指定内容）。...表1 成功的客户端请求 ? 表2 — 客户端重定向请求 表3中的响应代码表示客户端请求无效，如果条件不发生变化，重新请求仍无法处理。这些故障可能有请求格式错误、未授权的请求、请求的资源不存在等。 ?...表3 客户端请求错误 最后，表4中的响应代码表示服务器暂时无法处理客户端请求（可能仍然无效）。客户端应当在将来的某个时候重新请求。 ?...表4 服务器处理请求错误 服务根据其自身功能要求具有不同程度的可扩展性。 注意： 试试响应代码418，它会返回简洁有力的回复："我是一个茶壶。"
正如我们在 POST 部分中讨论的那样，通常不会出现这种情况。但是如果客户端能够控制服务器端信息空间，那么这种操作也是合理的。...DELETE 请求意在实现等幂。可能由于网络故障 DELETE 请求被打断，这时我们希望客户端继续尝试。第一次请求无论成功与否，资源都应该返回204（无指定内容）。...表1 成功的客户端请求 ? 表2 — 客户端重定向请求 表3中的响应代码表示客户端请求无效，如果条件不发生变化，重新请求仍无法处理。这些故障可能有请求格式错误、未授权的请求、请求的资源不存在等。...表3 客户端请求错误 最后，表4中的响应代码表示服务器暂时无法处理客户端请求（可能仍然无效）。客户端应当在将来的某个时候重新请求。 ?...表4 服务器处理请求错误 服务根据其自身功能要求具有不同程度的可扩展性。 注意： 试试响应代码418，它会返回简洁有力的回复："我是一个茶壶。"
另一方面，还有一些更新的、更现代的参与者，尝试着从基于 REST 的 API 中获得一些关注。当然，我指的是 GraphQL。...我们可以说，GET 请求是安全的，也是可执行的。 POST 方法 当你发出 POST 请求时，全世界每个人都想让你存储一些信息。...REST APIs 基本上是以 URI 为基础的，我想我们应该保持这一传统，使用基于 URI 的版本管理。...那么，让我们来想象一下，有一位用户在自己的手机中发送了一封无效的电子邮件。它以某种方式被传送到 API，API 自然会出发一次确认和错误，并且响应 400（错误请求）。...与此同时，API 应当发出一种通用的错误响应模式，使客户端能够将任意或全部的信息显示给终端用户。所以，如果是这样的话，你很有可能会返回一个错误信息：“输入的电子邮件地址无效”。
两周前因为公司一次裁人，好几个人的活都被按在了我头上，这其中的一大部分是一系列REST API，撰写者号称基本完成，我测试了一下，发现尽管从功能的角度来说，这些API实现了spec的显式要求，但是从实际使用的角度...POST: 创建一个新的资源。 PUT: 替换某个已有的资源。PUT操作虽然有副作用，但其应该是幂等的。 PATCH（RFC5789）: 修改某个已有的资源。 DELETE：删除某个资源。...如果自己手写REST API，一定要注意区分POST/PUT/PATCH/DELETE的应用场景。...你可以把请求数据验证看成一个巨大的漏斗，把不必要的访问统统过滤在第一线： Request headers是否合法：如果出现了某些不该有的头，或者某些必须包含的头没有出现或者内容不合法，根据其错误类型一律返回...Request URI和Request body是否合法：如果请求带有了不该有的数据，或者某些必须包含的数据没有出现或内容不合法，一律返回4xx。
URI包括URL和URN，在这里更多时候可能代指URL(统一资源定位符)。RESTful是面向资源的，每种资源可能由一个或多个URI对应，但一个URI只指向一种资源。...而RESTful风格的API则要求在URL上都以名词的方式出现，从几种请求方式上就可以看出想要进行的操作，这点与非RESTful风格的API形成鲜明对比。...400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。...且POST请求的请求参数都是请求体中，其大小是没有限制的。 在本案例中，我们设计以下POST请求的API。 POST /dogs ：服务端新增一个dog资源。...总结 RESTful风格的API 固然很好很规范，但大多数互联网公司并没有按照或者完全按照其规则来设计，因为REST是一种风格，而不是一种约束或规则，过于理想的RESTful API 会付出太多的成本。
什么是RESTful API ? RESTful API 是应用程序接口 (API) 的一种架构风格，它使用 HTTP 请求来访问和使用数据。...get和post了：客户端请求传统url接口REST ful风格接口查询所有用户 /user/findAllGET /users查询编号为1的用户 /user/findById?...状态码主要分为五大类：1xx：相关信息2xx：操作成功3xx：重定向4xx：客户端错误5xx：服务器错误例如：200：请求成功201：资源创建成功400：请求参数错误401：未授权访问403：表示禁止访问资源...案例 详情请见：https://restfulapi.cn/总结 RESTful风格的API 固然很好很规范，但大多数互联网公司并没有按照或者完全按照其规则来设计，因为REST是一种风格，而不是一种约束或规则...我正在参与2023腾讯技术创作特训营第三期有奖征文，组队打卡瓜分大奖！
误区一 请求路径 URI 是动词，而不是名词问题 误区二 URI中带版本号问题 误区三 URI 中路径大小写问题 误区一 请求路径 URI 是动词，而不是名词问题 按照对 Restful 架构风格理解，...比方说，设计产品列表接口时： 错误写法 /getProductList 请求路径 /getProductList 路径出现动词 get，这种写法是不对的。...第一种说法是，在请求路径中加入版本号，比方说： POST /products/v1 GET /users/v1 POST /orders/v1 POST /items/v1 这种说法认为，在 URI...还有一种说法是，在路径中加版本号是错误的设计方式，在老外写的 Versioning REST Services 这篇文章指出，你应该在请求头的 Accept 指定你的版本号，而不是请求路径中。...误区三 URI 中路径大小写问题 URL 中路径最好是小写，不要有驼峰式写法，比如下面接口错误写法 POST /orderItems/v1/1001 推荐写法 POST /orders/v1/items
四、基于Rest的Controller（控制器） 我们的 REST API : GET 方式请求 /api/user/ 返回用户列表 GET 方式请求 /api/user/1返回id为1的用户 POST...方式请求 /api/user/ 通过user对象的JSON 参数创建新的user对象 PUT 方式请求 /api/user/3 更新id为3的发送json格式的用户对象 DELETE 方式请求/api...五、发布和测试此API 想要测试此API，我将使用POSTMAN这个外部客户端，接下来我们也将写我们自己的客户端。 1. 获取所有用户 打开 POSTMAN工具，选择请求类型为GET，指明uri ?...现在试着发送一个带有错误识别码的GET请求，将收到一个HTTP 404 ?...六、根据RestTemplate 写REST Client Postman是测试Rest Api的超好用的工具，但是如果你想完整的消化REST，可以尝试自己写一个。
最常见的就是Code和Message，当然对于这一点，我个人是保留疑问的，我的观点是，Http本身的错误和服务器的内部错误还是需要在不断层面分开的，不能混在一起。可是在大神眼里并非如此。...在过去的混乱世界里，经常用的就是Get和Post。如果不是因为Get不支持大数据传输，我想连Post都不会有人使用。...URI 的设计只要负责把资源通过合理方式暴露出来就可以了。对资源的操作与它无关，操作是通过 HTTP动词来体现，所以REST 通过 URI 暴露资源时，会强调不要在 URI 中出现动词。...比如：左边是错误的设计，而右边是正确的 GET /rest/api/getDogs --> GET /rest/api/dogs 获取所有小狗狗 GET /rest/api/addDogs...--> POST /rest/api/dogs 添加一个小狗狗 GET /rest/api/editDogs/:dog_id --> PUT /rest/api/dogs/:dog_id 修改一个小狗狗
通用错误响应 503 （Service Unavailable）- 服务端当前无法处理请求 POST 不安全且不幂等 使用服务端管理的（自动产生）的实例号创建资源 创建子资源 部分更新资源 如果没有被修改...500 （internal server error）- 通用错误响应 503 （Service Unavailable）- 服务端当前无法处理请求 下面我们来看一些实践中常见的问题: POST和PUT...我认为，这是因为rails默认使用服务端生成的ID作为URI的缘故，而不少人就是通过rails实践REST的，所以很容易造成这种误解。 客户端不一定都支持这些HTTP方法吧?...这样的方式对于客户端来说，无疑是更为直观，但混淆了资源的名称和资源的表述形式。 我个人认为，还是应该优先使用内容协商来区分表述格式。...2. 4 资源的链接 我 们知道REST是使用标准的HTTP方法来操作资源的，但仅仅因此就理解成带CURD的Web数据库架构就太过于简单了。
通用错误响应 503 （Service Unavailable）- 服务端当前无法处理请求 POST 不安全且不幂等 使用服务端管理的（自动产生）的实例号创建资源 创建子资源 部分更新资源 如果没有被修改...500 （internal server error）- 通用错误响应 503 （Service Unavailable）- 服务端当前无法处理请求 下面我们来看一些实践中常见的问题: POST和PUT...我认为，这是因为rails默认使用服务端生成的ID作为URI的缘故，而不少人就是通过rails实践REST的，所以很容易造成这种误解。 客户端不一定都支持这些HTTP方法吧?...下面我们来看一些实践上常见的设计: 在URI里边带上版本号 有些API在URI里边带上版本号，例如: http://api.example.com/1.0/foo http://api.example.com...这样的方式对于客户端来说，无疑是更为直观，但混淆了资源的名称和资源的表述形式。 我个人认为，还是应该优先使用内容协商来区分表述格式。
本来我以为在国内有很多公司都在用jira， 这里面少不了的API接口进行功能性的封装，肯定会有中文的文档结果经过几次尝试搜索之后，我终于确认jira API是没有中文文档的。...我使用的一键翻译软件是浏览器自带的尝试过一些，他们总是会把接口请求路径中的英文单词也翻译成汉字，这简直就是不能看。...在我搜索中文文档的过程中，我看到网上有很多人对API的实现进行了分享，对我来说还是有点大帮助的。但内容比较少，仅限于两三个特别常用的API。...201 Created 请求已经被实现，而且有一个新的资源已经依据请求的需要而建立，且其 URI 已经随Location 头信息返回。...会让我付出更多的时间和精力去纠正这些错误，如果再碰到非常复杂的包装格式，就更让人恼火了。回到刚才提到过的Jira api文档，有非常多个版本，如果文档出现错误，修复起来肯定也是比较多的。
这导致API构架的流行，甚至出现”APIFirst”的设计思想。RESTful API是目前比较成熟的一套互联网应用程序的API设计理论。...安全性 幂等性 GET √ √ POST × × PUT × √ DELETE × √ 安全性和幂等性均不保证反复请求能拿到相同的response。...错误处理 不要发生了错误但给2xx响应，客户端可能会缓存成功的http请求； 正确设置http状态码，不要自定义； Response body 提供 1) 错误的代码（日志/问题追查）；2) 错误的描述文本...Header：X-Api-Version: 1 用第一种，虽然没有那么优雅，但最明显最方便。...URI失效 随着系统发展，总有一些API失效或者迁移，对失效的API，返回404 not found 或 410 gone；对迁移的API，返回 301 重定向。
REST API 设计人员应该创建 URI，将 REST API 的资源模型传达给潜在的客户端开发人员。在这篇文章中，我将尝试为 REST API URsI 引入一套设计规则。...两个不同的 URI 映射到两个不同的资源。如果 URI 不同，那么资源也会不同，反之亦然。因此，REST API 必须生成和传达清晰的 URI，并且不应容忍任何客户端尝试去对一个资源进行模糊的标识。...RFC 3986 中将 URI 定义为区分大小写，但协议头和域名除外。...应鼓励 REST API 客户端使用 HTTP 提供的格式选择机制，即请求 header 中的 Accept 属性。...虽然你的语法常识会告诉你使用复数来描述资源的单个实例是错误的，但实际的答案是保持 URI 格式一致并且始终使用复数形式。
领取专属 10元无门槛券
手把手带您无忧上云
云服务器
即时通信 IM
ICP备案
对象存储
实时音视频
