单一 API 端点的优缺点

Posted 2023-02-19

【中文标题】单一 API 端点的优缺点

【英文标题】：Single API endpoint pros and cons

【发布时间】：2019-09-03 05:10:10

【问题描述】：

我正在创建 API 并试图找出计划好的方法。 该 API 不是公开的，它将被我构建的 SPA 和移动应用程序使用。所以我正在考虑类似 GraphQL 的设计，但没有发布 json 并使用常规 HTTP 方法。 GET 方法是这样的：

示例1-获取具有特定字段的用户（_join表示sql表连接），排序和限制：api.com?table=users&displayFields=id,name,email,address,tel,country_join&orderBy=asc&orderColumn=name&offset=0&limit=10

示例 2 - 根据包含所有字段、排序和限制的搜索参数获取用户：api.com?table=users&search=John&searchFields=name,email&orderBy=asc&orderColumn=name&offset=0&limit=10

我认为这很糟糕，因为 REST 是标准的，否则我会看到更多这种方法的示例。 但是为什么会这样呢？对我来说，它似乎更容易开发并且使用起来更灵活。 我提供的示例的适当 REST API 是否更易于实现、更安全、更易于使用或缓存？

【参考方案1】：

我看到将变量放在 url 和请求正文中的主要区别是：

数据长度作为url长度是有限制的，而请求体没有 url中需要转义的特殊字符会导致url长且不清晰

这些是支持请求正文中数据的 2 个专家，但我同意 url 中的数据更易于测试和使用，因为您不需要 curl 或 postman 等 http 客户端工具来验证您的端点。

如果你想完全实现它，REST 有更严格的约定：

使用正确的 http 请求（get、post、patch、delete 和 put）在一个端点上实现 crud 操作 作为结果返回正确的 http 代码 使用标准数据格式进行输入和输出（json 或 XML）

为了更好地实现系统之间的互操作性，建议遵循 REST 和微服务设计模式。

对于小型应用程序，我们可以遵循一些捷径而不完全遵守。到目前为止，我已经集成了几项服务，每次我都可以告诉你没有一个服务实现了标准 REST :-)

【讨论】：

它将返回正确的http代码并输出json。并且还将使用正确的 http 方法，但不是以正确的 REST 方式。例如发布api.com?table=users。关于数据长度，我不打算在其中包含很多字段。因为最大的参数将是displayFields，并且最大为 5-6，否则我将排除该参数并返回所有字段，因此 url 长度不会有问题

是的，这应该很好！只需确保在设计端点时遵循相同的逻辑并使用一个变量来定义您正在调用的请求（例如 request=adduser）。这可能与您编写的表变量相同。还要确保响应返回状态字段和错误字段。