单一 API 端点的优缺点 [英] Single API endpoint pros and cons

问题描述

我正在创建 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=名称&offset=0&limit=10

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

解决方案

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

• 数据长度限制为url长度，请求体不限制
• url中需要转义的特殊字符，可能导致url长而不清楚

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

但是，如果您想完全实现 REST，则它具有更严格的约定:

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

为了提高系统之间的互操作性，建议遵循 REST 和微服务设计模式.

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

I am creating API and trying to figure out is planned approach any good.
That API is not public and it will be used by SPA and mobile app that I build.
So I am thinking of GraphQL-like design but without posting json and with regular HTTP methods. Something like this for GET methods:

Example 1 - get users with specific fields(_join indicates sql table join), ordering and limit:
api.com?table=users&displayFields=id,name,email,address,tel,country_join&orderBy=asc&orderColumn=name&offset=0&limit=10

Example 2 - get users based on search parameters with all fields, ordering and limit:
api.com?table=users&search=John&searchFields=name,email&orderBy=asc&orderColumn=name&offset=0&limit=10

I assume this is bad since REST is standard, otherwise I would see much more examples of this approach.
But why is this bad? For me it seems easier to develop and more flexible to use.
Is proper REST API for examples I provided easier to implement, safer, easier to use or cache?

解决方案

The main difference I see between putting the variables in the url vs the request body are:

• the length of the data as the url length is limited while the request body is not
• special characters to be escaped in the url which can lead to long and unclear url

These are 2 pros in favor of data in request body, but I agree that data in url is much simpler to test and use as tou don't need an http client tool like curl or postman to validate your endpoints.

REST however has stricter conventions if you want to fully implement it:

• use the right http requests (get, post, patch, delete and put) to implement crud operations on one single endpoint
• return the right http code as a result
• use standard data format for input and output (json or XML)

For better interoperability between systems it's advised to comply with REST and microservices design patterns.

For small applications we can follow some shortcuts and not comply fully. I have integrated several services so far and each time I can tell you no one of them implements standard REST :-)

这篇关于单一 API 端点的优缺点的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！