让我流失用户的 5 个 REST API 错误

三年前，我构建了我的第一个公开 API。我以为一个周末就能搞定。我等着用户到来。

他们来了。然后又离开了。

产品没问题。API 很难用。我犯了五个重大错误。以下是我修复它们的方法。

1. 使用 200 OK 表示错误

即使在请求失败时，我也发送 200 OK 状态码。我把错误信息放在 JSON 体中。这迫使开发者必须为每一次调用编写自定义逻辑。

修复方法：使用正确的 HTTP 状态码。

• 输入错误使用 400。
• 身份验证失败使用 401。
• 资源缺失使用 404。
• 触发频率限制使用 429。

2. 忘记版本控制

我在没有预警的情况下更改了数据字段。一次改动就破坏了我所有的集成。

修复方法：在路由前加上 /v1/ 前缀。 这可以防止在更新代码时破坏现有的客户端。请保留当前版本和上一个版本。

3. 没有频率限制

一个有 Bug 的脚本每秒请求我的搜索端点 200 次。它耗尽了我的数据库资源，导致其他所有人的系统都崩溃了。

修复方法：实现频率限制。 使用令牌桶（token-bucket）算法。返回 429 Too Many Requests 状态码，并附带 Retry-After 请求头。

4. 错误格式不一致

我的错误信息看起来各不相同，取决于错误发生的位置。一个错误使用 "msg"，而另一个使用 "message"。开发者不得不为同一个 API 编写多个解析器。

修复方法：选定一种错误结构并贯穿始终。 每个错误都应该拥有相同的键（keys）。

5. 返回数据过多

我的 /users 端点返回了数据库中的每一个用户。当我们达到 10,000 个用户时，响应体的大小导致移动端应用崩溃。

修复方法：使用基于游标（cursor-based）的分页。 这能保持响应体小巧且稳定。对于大数据集，它比基于偏移量（offset-based）的分页更快。

结果：

• 集成时间从 3 天降至 4 小时。
• 技术支持工单减少了 70%。
• 以前的用户回来了。

你的 API 就是你的产品。优秀的的前端无法拯救一个糟糕的 API。

你见过最糟糕的 API 错误是什么？在评论区告诉我吧。

Source: https://dev.to/sirmax/5-rest-api-mistakes-that-cost-me-users-and-how-to-fix-them-57gi