您当前的位置:首页 > 电脑百科 > 程序开发 > 编程百科

API状态和错误码

时间:2020-02-29 12:16:40  来源:  作者:

状态代码和错误代码是指响应头中的代码号,用于指示响应的常规分类,例如,请求是否成功(200),是否导致服务器错误(500),是否存在授权问题(403),等等。标准状态代码通常不需要太多文档,但是特定于您的API的自定义状态和错误代码则需要。错误代码特别有助于解决不良请求。

目录

  • curl标头中的状态码示例
  • 列出HTTP响应和错误码的位置
  • 在哪里获取状态和错误码
  • 如何列出状态码
  • 状态/错误代码可以帮助进行故障排除
  • 状态和错误码示例Context.ioTwitterMailchimpFlickr
  • 具有状态和错误代码的活动

curl标头中的状态码示例

状态码未出现在响应正文中。它们显示在响应标题中,默认情况下您可能看不到。还记得您在“curl调用方法”中提交了curl调用吗?要获取响应头,请在curl请求中添加--include或-i。如果您只想在响应中返回响应标头(而不要返回其他任何内容),请大写-I,如下所示:

curl -I -X GET "https://api.openweathermap.org/data/2.5/weather?zip=95050&Appid=fd4698c940c6d1da602a70ac34f0b147&units=imperial"

响应头如下所示:

HTTP/1.1 200 OKServer: openrestyDate: Thu, 06 Dec 2018 22:58:41 GMTContent-Type: application/json; charset=utf-8Content-Length: 446Connection: keep-aliveX-Cache-Key: /data/2.5/weather?units=imperial&zip=95050Access-Control-Allow-Origin: *Access-Control-Allow-Credentials: trueAccess-Control-Allow-Methods: GET, POST

第一行HTTP / 1.1 200 OK告诉我们请求的状态(200)。大多数REST API都遵循响应头的标准协议。例如,200不仅仅是OpenWeatherMap API开发人员确定的任意代码。200是用于成功HTTP请求的通用代码。(如果您更改方法,则会获得其他状态代码。)

有了GET请求,很容易判断请求是否成功,因为您会获得预期的响应。但是,假设您要进行POST,PUT或DELETE调用,那么您将在其中更改资源中包含的数据。您如何知道API是否成功处理并接收了请求?响应标头中的HTTP响应代码将指示操作是否成功。HTTP状态代码只是较长消息的缩写。

API状态和错误码

状态代码非常微妙,但是当开发人员使用API​​时,这些代码可能是开发人员拥有的唯一“接口”。如果您可以

状态码通常不提供信息,编写得很差,并且很少或没有向用户传达有用的信息来克服该错误。最终,状态码应帮助用户从错误中恢复。

您可以在此处查看常见的REST API状态代码列表,并在此处查看HTTP状态代码的常规列表。尽管最好包含一些标准状态代码,但是不需要全面记录所有标准状态代码,尤其是在您的API很少触发的情况下。

列出HTTP响应和错误码的位置

大多数API应该有一个通用页面,其中列出了整个API的响应和错误代码。一个单独的页面列出了状态代码(而不是在每个端点中包括这些状态代码),使您可以更详细地扩展每个代码,而不会占用其他文档。它还减少了冗余和信息过载感。

另一方面,如果某些端点比其他端点更容易触发某些状态和错误代码,则在相同的API参考页面上突出显示这些状态和错误代码是有意义的。一种策略可能是引起注意特定端点的任何特别相关的状态或错误代码,然后链接到集中的“响应和状态代码”页面以获取完整信息。

在哪里获取状态和错误代码

在记录API时,状态代码和错误代码可能并不明显。您可能需要向开发人员索要API独有的所有状态和错误代码的列表。有时,开发人员会直接在编程代码中对这些状态和错误代码进行硬编码,而没有简单的方法来向您提供完整的列表(这也使本地化成为问题)。结果,您可能需要尝试一下以找出所有代码。

具体来说,您可能需要尝试破坏API才能查看所有潜在的错误代码。例如,如果您超出了特定呼叫的速率限制,则API可能会返回特殊错误或状态代码。您尤其需要记录此自定义代码。API中的疑难解答部分可能会特别使用错误代码。

如何列出状态码

您可以在基本表或定义列表中列出状态和错误代码,如下所示:

API状态和错误码

 

状态/错误代码可以帮助进行故障排除

状态和错误代码在进行故障排除时特别有用。因此,您可以将这些错误代码视为故障排除部分的补充。几乎所有的文档集都可以从故障排除一节中受益。

在故障排除主题中,您记录了当用户走开快乐的道路并在黑暗的森林中迷路时发生的情况。状态代码就像照明不佳的步道标志一样,可以帮助用户回到正确的道路上。

有关疑难解答的一节可能列出与以下情况有关的错误消息:

  • 使用了错误的API密钥
  • 使用了无效的API密钥
  • 参数不适合数据类型
  • API引发异常
  • 没有数据可返回的资源
  • 已超出速率限制
  • 参数超出了可接受的最大值和最小值范围
  • 端点缺少必需的参数

尽可能在文档中记录错误的确切文本,以便在搜索时轻松显示该错误。

状态和错误代码示例

以下是API文档中的一些示例状态和错误代码页。

Context.io

 

API状态和错误码

Context.io状态和错误代码

Clearbit不仅记录了标准状态码,而且还描​​述了其API返回的唯一参数。大多数开发人员可能会熟悉200、400和500的代码,因此这些代码不需要太多解释性的细节。但是,如果您的API具有唯一的代码,请确保充分描述它们。

Twitter

API状态和错误码

Twitter状态和错误代码

借助Twitter的状态代码文档,他们不仅可以描述代码和状态,还可以提供有用的故障排除信息,从而可能有助于错误恢复。例如,对于500错误,作者不只是说状态是指服务中断,他们还解释说:“这通常是暂时的错误,例如在高负载情况下,或者端点暂时有问题。如果其他人遇到类似问题,请登录开发者论坛,或者稍后再试。”

这种有用的信息是技术作者应针对状态代码(至少对于那些指示问题的代码)的目标。

Mailchimp

API状态和错误码

Mailchimp状态和错误代码

Mailchimp提供了错误消息的可读且友好的描述。例如,对于403错误,Mailchimp不仅仅是写“ Forbidden”,还解释了为什么您可能会收到Forbidden代码的原因。使用Mailchimp,有几种类型的403错误。您的请求可能由于用户帐户被禁用或对错误的数据中心的请求而被禁止。对于“ WrongDataCenter”错误,Mailchimp指出“它通常与配置错误的库相关联”,并且它们链接到有关数据中心的更多信息。这是对用户有用的错误代码文档。

Flickr

API状态和错误码

Flickr的状态和错误代码

使用Flickr,“响应代码”部分嵌入在每个API参考主题中。因此,描述简短。在每个主题中嵌入响应代码会使错误代码更明显,但在某些方面却没有太大帮助。因为它嵌入在每个API主题中,所以有关错误代码的描述必须简短,否则内容将使端点请求信息不堪重负。

相比之下,列出错误代码的独立页面使您可以在不排挤其他文档的情况下更详细地扩展每个代码。独立页面还可以减少冗余并减少大量信息(只是重复的信息)的显示。

如果某些端点比其他端点更容易触发某些状态和错误代码,则在其相关的API参考页上突出显示这些状态和错误代码是有意义的。建议您注意端点页面上任何特别相关的状态或错误代码,然后链接到集中页面以获取完整信息。

具有状态和错误代码的活动

使用您确定的开源项目,确定状态和错误代码信息。回答以下问题:

  • 项目是否描述状态和错误代码?状态和错误代码信息在文档上下文中位于何处?作为独立主题?在每个端点之下?别的地方?
  • API是否具有任何唯一的状态和错误代码?
  • 错误代码是否可以帮助用户从错误中恢复?
  • 向其中一个端点发出请求。然后有意地更改参数,以使其无效。响应中返回什么状态码?是否记录了此状态码?


Tags:API   点击:()  评论:()
声明:本站部分内容及图片来自互联网,转载是出于传递更多信息之目的,内容观点仅代表作者本人,如有任何标注错误或版权侵犯请与我们联系(Email:2595517585@qq.com),我们将及时更正、删除,谢谢。
▌相关推荐
近日只是为了想尽办法为 Flask 实现 Swagger UI 文档功能,基本上要让 Flask 配合 Flasgger, 所以写了篇 Flask 应用集成 Swagger UI 。然而不断的 Google 过程中偶然间发现了...【详细内容】
2021-12-23  Tags: API  点击:(6)  评论:(0)  加入收藏
一个项目的大部分API,测试用例在参数和参数值等信息会有很多相似的地方。我们可以复制API,复制用例来快速生成,然后做细微调整既可以满足我们的测试需求1.复制API:在菜单发布单...【详细内容】
2021-12-14  Tags: API  点击:(20)  评论:(0)  加入收藏
10月18号, W3C中网络平台孵化器小组(Web Platform Incubator Community Group)公布了HTML Sanitizer API的规范草案。这份草案用来解决浏览器如何解决XSS攻击问题。 网络安全中...【详细内容】
2021-12-07  Tags: API  点击:(20)  评论:(0)  加入收藏
当我们通过kubectl来查看、修改Kubernetes资源时,有没有想过后面的接口到底是怎样的?有没有办法探查这些交互数据呢?Kuberenetes客户端和服务端交互的接口,是基于http协议的。所...【详细内容】
2021-11-23  Tags: API  点击:(29)  评论:(0)  加入收藏
前言客户端请求API,通常需要通过返回码来判断API返回的结果是否符合预期,以及该如何处理返回的内容等。相信很多同学都吃过返回码定义混乱的亏,有的API用返回码是int类型,有的是...【详细内容】
2021-10-28  Tags: API  点击:(52)  评论:(0)  加入收藏
凭借着平缓的学习曲线和简单直接的语法,Python在全球范围内的受欢迎程度,正在呈指数级增长。该编码语言往往可以被用于Web开发、软件开发、数学计算、系统脚本、以及几乎所有...【详细内容】
2021-09-22  Tags: API  点击:(48)  评论:(0)  加入收藏
Guava提供的RateLimiter可以限制物理或逻辑资源的被访问速率,咋一听有点像java并发包下的Samephore,但是又不相同,RateLimiter控制的是速率,Samephore控制的是并发量。RateLimit...【详细内容】
2021-09-17  Tags: API  点击:(72)  评论:(0)  加入收藏
前言前后端分离开发模式中,api文档是最好的沟通方式。今天就来说一说如何整合Swagger生成一套漂亮、美观、实用的接口文档。 源码传送门: https://gitee.com/huoqstudy/xiliu-...【详细内容】
2021-09-08  Tags: API  点击:(65)  评论:(0)  加入收藏
注:商业级功能效果演示,非开源,无源码。研发基础在之前AJAX请求数据加密效果之上,更进一步,对返回数据加密。之前是单纯用于登录场景。更广泛的场景是所有此类AJAX WEB API接口。...【详细内容】
2021-09-03  Tags: API  点击:(75)  评论:(0)  加入收藏
最近一连串的 API 安全事件(Peloton、Experian、Clubhouse 等)无疑迫使许多安全和开发团队仔细检查他们的 API 安全状况,以确保它们不会成为下一个被攻击对象。创建面向外部受...【详细内容】
2021-09-01  Tags: API  点击:(59)  评论:(0)  加入收藏
▌简易百科推荐
本文分为三个等级自顶向下地分析了glibc中内存分配与回收的过程。本文不过度关注细节,因此只是分别从arena层次、bin层次、chunk层次进行图解,而不涉及有关指针的具体操作。前...【详细内容】
2021-12-28  linux技术栈    Tags:glibc   点击:(3)  评论:(0)  加入收藏
摘 要 (OF作品展示)OF之前介绍了用python实现数据可视化、数据分析及一些小项目,但基本都是后端的知识。想要做一个好看的可视化大屏,我们还要学一些前端的知识(vue),网上有很多比...【详细内容】
2021-12-27  项目与数据管理    Tags:Vue   点击:(2)  评论:(0)  加入收藏
程序是如何被执行的  程序是如何被执行的?许多开发者可能也没法回答这个问题,大多数人更注重的是如何编写程序,却不会太注意编写好的程序是如何被运行,这并不是一个好...【详细内容】
2021-12-23  IT学习日记    Tags:程序   点击:(9)  评论:(0)  加入收藏
阅读收获✔️1. 了解单点登录实现原理✔️2. 掌握快速使用xxl-sso接入单点登录功能一、早期的多系统登录解决方案 单系统登录解决方案的核心是cookie,cookie携带会话id在浏览器...【详细内容】
2021-12-23  程序yuan    Tags:单点登录(   点击:(8)  评论:(0)  加入收藏
下载Eclipse RCP IDE如果你电脑上还没有安装Eclipse,那么请到这里下载对应版本的软件进行安装。具体的安装步骤就不在这赘述了。创建第一个标准Eclipse RCP应用(总共分为六步)1...【详细内容】
2021-12-22  阿福ChrisYuan    Tags:RCP应用   点击:(7)  评论:(0)  加入收藏
今天想简单聊一聊 Token 的 Value Capture,就是币的价值问题。首先说明啊,这个话题包含的内容非常之光,Token 的经济学设计也可以包含诸多问题,所以几乎不可能把这个问题说的清...【详细内容】
2021-12-21  唐少华TSH    Tags:Token   点击:(10)  评论:(0)  加入收藏
实现效果:假如有10条数据,分组展示,默认在当前页面展示4个,点击换一批,从第5个开始继续展示,到最后一组,再重新返回到第一组 data() { return { qList: [], //处理后...【详细内容】
2021-12-17  Mason程    Tags:VUE   点击:(14)  评论:(0)  加入收藏
什么是性能调优?(what) 为什么需要性能调优?(why) 什么时候需要性能调优?(when) 什么地方需要性能调优?(where) 什么时候来进行性能调优?(who) 怎么样进行性能调优?(How) 硬件配...【详细内容】
2021-12-16  软件测试小p    Tags:性能调优   点击:(20)  评论:(0)  加入收藏
Tasker 是一款适用于 Android 设备的高级自动化应用,它可以通过脚本让重复性的操作自动运行,提高效率。 不知道从哪里听说的抖音 app 会导致 OLED 屏幕烧屏。于是就现学现卖,自...【详细内容】
2021-12-15  ITBang    Tags:抖音防烧屏   点击:(25)  评论:(0)  加入收藏
11 月 23 日,Rust Moderation Team(审核团队)在 GitHub 上发布了辞职公告,即刻生效。根据公告,审核团队集体辞职是为了抗议 Rust 核心团队(Core team)在执行社区行为准则和标准上...【详细内容】
2021-12-15  InfoQ    Tags:Rust   点击:(25)  评论:(0)  加入收藏
最新更新
栏目热门
栏目头条