使用一长串查询参数设计 RESTful 查询 API [英] Design RESTful query API with a long list of query parameters

问题描述

我需要设计一个 RESTful 查询 API，它根据几个过滤器返回一组对象.通常的 HTTP 方法是 GET.唯一的问题是，它至少可以有十几个过滤器，如果我们将所有过滤器都作为查询参数传递，则 URL 可能会变得很长(足够长以致于被某些防火墙阻止).

I need to design a RESTful query API, that returns a set of objects based on a few filters. The usual HTTP method for this is GET. The only problem is, it can have at least a dozen filters, and if we pass all of them as query parameters, the URL can get quite long (long enough to be blocked by some firewall).

减少参数数量不是一种选择.

Reducing the numbers of parameters is not an option.

我能想到的一种替代方法是在 URI 上使用 POST 方法并将过滤器作为 POST 正文的一部分发送.这是否反对 RESTfull(对查询数据进行 POST 调用).

One alternative I could think of is to make use of the POST method on the URI and send the filters as part of the POST body. Is this against being RESTfull (Making a POST call to query data).

有人有更好的设计建议吗?

Anyone have any better design suggestions?

推荐答案

请记住，对于 REST API，这完全取决于您的观点.

Remember that with a REST API, it's all a question of your point of view.

REST API 中的两个关键概念是端点和资源(实体).粗略地说，端点要么通过 GET 返回资源，要么通过 POST 和 PUT 等(或以上的组合)接受资源.

The two key concepts in a REST API are the endpoints and the resources (entities). Loosely put, an endpoint either returns resources via GET or accepts resources via POST and PUT and so on (or a combination of the above).

可以接受的是，使用 POST，您发送的数据可能会也可能不会导致创建新资源及其关联的端点，这很可能不会在 POST 的 url 下存活".换句话说，当您 POST 时，您将数据发送到某处进行处理.POST 端点不是通常可以找到资源的位置.

It is accepted that with POST, the data you send may or may not result in the creation of a new resource and its associated endpoint(s), which will most likely not "live" under the POSTed url. In other words when you POST you send data somewhere for handling. The POST endpoint is not where the resource might normally be found.

引用 RFC 2616(省略不相关部分，突出显示相关部分):

Quoting from RFC 2616 (with irrelevant parts omitted, and relevant parts highlighted):

POST 方法用于请求源服务器接受包含在请求中的实体作为资源的新从属由请求行中的请求 URI 标识.POST 旨在允许一个统一的方法来覆盖以下功能:

9.5 POST

The POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line. POST is designed to allow a uniform method to cover the following functions:

• ...
• 向数据处理过程提供数据块，例如提交表单的结果；
• ...

...

POST 方法执行的操作可能不会产生可由 URI 识别的资源.在这种情况下，200(正常)或 204(无内容)是适当的响应状态，具体取决于响应是否包含描述结果的实体.

The action performed by the POST method might not result in a resource that can be identified by a URI. In this case, either 200 (OK) or 204 (No Content) is the appropriate response status, depending on whether or not the response includes an entity that describes the result.

如果在源服务器上创建了资源，响应应该是 201 (Created)...

If a resource has been created on the origin server, the response SHOULD be 201 (Created)...

我们已经习惯于代表事物"或数据"的端点和资源，无论是用户、消息还是书籍——无论问题域要求什么.但是，端点也可以公开不同的资源 - 例如搜索结果.

We have grown used to endpoints and resources representing 'things' or 'data', be it a user, a message, a book - whatever the problem domain dictates. However, an endpoint can also expose a different resource - for example search results.

考虑以下示例:

GET    /books?author=AUTHOR
POST   /books
PUT    /books/ID
DELETE /books/ID

这是典型的 REST CRUD.但是，如果我们添加:

This is a typical REST CRUD. However what if we added:

POST /books/search

    {
        "keywords": "...",
        "yearRange": {"from": 1945, "to": 2003},
        "genre": "..."
    }

此端点没有任何非 RESTful.它以请求正文的形式接受数据(实体).该数据是搜索标准 - 与其他任何 DTO 一样.此端点生成资源(实体)以响应请求:搜索结果.搜索结果资源是临时资源，可立即提供给客户端，无需重定向，也不会从其他规范网址公开.

There is nothing un-RESTful about this endpoint. It accepts data (entity) in the form of the request body. That data is the Search Criteria - a DTO like any other. This endpoint produces a resource (entity) in response to the request: Search Results. The search results resource is a temporary one, served immediately to the client, without a redirect, and without being exposed from some other canonical url.

它仍然是 REST，除了实体不是书籍 - 请求实体是书籍搜索条件，响应实体是书籍搜索结果.

It's still REST, except the entities aren't books - the request entity is book search criteria, and the response entity is book search results.

这篇关于使用一长串查询参数设计 RESTful 查询 API的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！