我正在开发针对远程服务器运行的 iOS 应用程序,背后有另一个开发人员。我们正在编写的项目和 API 草案处于初始阶段。
我们面临的问题是我们对 HTTP/REST 规范描述的现有大量常规状态代码不满意:在某些情况下我们不确定要选择什么代码。
提供最少上下文的示例:
服务器端验证错误。外汇。客户端验证没问题,但服务器 API 最近略有更改,因此服务器应该返回一些内容,表明这正是验证问题。
尝试注册已存在的用户。 SO 主题并未对此提供任何精确的观点。
用户已注册,并在未完成密码确认程序的情况下尝试登录。
我们在这里看到两种明显的方法:
对于找不到合适的常规状态代码的情况,使用 fx 400 错误。这将引导我们从 JSON 响应中解析错误文本消息。显然,这种方法会在客户端代码中引入多余的复杂性。
创建我们自己的子代码系统并在我们的代码中依赖它。这涉及太多人为的约定,这将导致我们变得过于自以为是和武断。
感觉这种情况的数量将会增加,我们正在考虑在我们的服务器应该提供的 JSON 响应中引入自定义子代码(即选择第二种方法)。
我在这里问的是:
对于这些情况,推荐的方法、策略、甚至粘合剂或技巧是什么?
不再严格遵循状态代码的 REST/HTTP 约定有哪些利弊?
谢谢!
最佳答案
对于验证问题,我使用 422 Unprocessable Entity (WebDAV; RFC 4918) 该请求格式正确,但由于语义错误而无法执行。这是因为请求失败不是因为格式错误的语法,而是因为语义。
然后为了进行通信,您只需要决定错误格式,因此对于情况 1,如果有必填字段,您可能会返回 422 以及以下内容。
{
"field": ["required"]
}
我会将第二个问题视为验证问题,因为它实际上是用户名的验证问题,所以 422 包含以下内容。
{
"username": ["conflict"]
}
第三个我会视为 403 Forbidden,因为传递授权 header 无济于事,并且会被禁止,除非他们执行传递凭据以外的操作。
你可以做类似 oauth2 的事情执行并返回一个人类可读的描述,一个人们可以根据其编码的常数,进一步澄清错误和一个 uri 以获取更多信息。
{
"error": "unfinished_registration",
"error_description": "Must finish the user registration process",
"error_uri": "http://yourdocumentation.com"
}
注意:您会发现人们对什么 http 代码映射到什么情况以及是否应该使用 422 持不同意见,因为它是 WebDAV 扩展的一部分,这很好,最您最重要的事情可以做的是记录代码的含义并保持一致,而不是完全符合它们的含义。
关于api - 在有争议的情况下选择合适的 HTTP 状态码还是引入子码?,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/12514338/