RESTful API 设计问答之一: 返回一个 200 OK 的空数组还是返回 404 Not Found

有人说过 API 设计师就是程序员的用户体验工程师。优秀的 API 设计应该在用户使用起来方便的同时程序员实现起来也很简单。

下面的系列文章是我的 API 设计工作中总结了一些技巧。大家看看是不是有用？您可以留言告诉我您的如何让 API 易用的想法。

返回一个 200 OK 的空数组还是返回 404 Not Found

问题

有时候，很难说一个 GET API 应该返回一个 200 OK 的空数组呢，还是返回 404 Not Found. 实际上，这取决于客户端希望怎么处理 API 的返回结果。

一个 4xx 的结果一般来说表示客户端的请求有问题。遇到 4xx 的返回结果，客户端一般会显示一个定制的错误页面。 在 API 设计师决定返回哪种结果前，最好先问问客户端程序员他们想怎么处理返回结果。

答案

然而，对于返回哪种状态码还是有一些常见的做法的。举例来说一个 API 应该返回带 200 OK 状态码的空数组，如果 API 的作用是用来按照某些条件搜索某个玩家的记录，因为没有记录只是表示没有查询到特定条件下的记录，并不是客户端的请求有问题。但是，API 应该返回 404 如果某个玩家在系统中找不到，因为用户可能在客户端输入了错误的玩家 ID，并且系统应该提示玩家这个错误。

示例

在下面的例子中， 系统试图搜索某个工作站的用户会话。API 会返回 200 OK 空数组如果没有正在使用的会话，但是如果工作站 ID 找不到的话会返回 404 错误。