使用 REST API 更改数组/集合顺序 [英] Change the array/collection order using a REST API

问题描述

您知道设计 REST 方法来改变小集合的顺序的任何最佳实践"吗?

我在GET/api/v1/items"中公开了一个集合.此端点返回一个 JSON 数组，每个项目都有一个唯一的 id.

我正在考虑创建PATCH/api/v1/items"并使用新订单发送一组 id.但我想知道是否有任何替代方案或设计模式可以正确完成此任务.

解决方案

遵循 REST Uniform Interface 约束，HTTP PUT 和 PATCH 方法必须坚持标准语义，因此您可以通过以下方式使用任一方法来做到这一点:

使用PUT，客户可以按照他们想要的顺序上传一个全新的表示.他们将请求GET/api/v1/items，根据需要更改顺序，然后使用PUT/api/v1/items 提交回来.

使用PATCH，客户可以发送diff 文档，根据需要执行订单更改.您可以使用像 json-patch 这样的格式，客户端使用 move 操作和数组路径执行更改.

请注意，这些都不是设计模式或最佳实践.它们只是 PUT 和 PATCH 方法应该如何工作.理想情况下，这应该适用于为该 URI 处的资源正确实现 GET、PUT 和 PATCH 方法的任何 RESTful 应用程序，这就是美妙之处的休息.如果你以正确的方式去做，你只需要做一次，客户就可以为每个人概括.例如，对于小集合，客户端可以选择 PUT 方式，对于较大的集合，可以选择 PATCH 方式.

您将 PATCH 与一个 id 数组一起使用的想法，以及@dit 建议使用 PUT 来做这件事的答案都不是真正的 RESTful，因为它们正在与标准语义:你不使用 delta 格式，他使用 PUT 进行部分更新.但是，如果使用 POST 完成，这两个选项都可以是 RESTful.POST 是执行任何未由 HTTP 协议标准化的操作的方法，因此您可以使用它做任何您想做的事情，但您必须记录具体如何去做.

所以，这取决于你.如果您完全关心 RESTful 并且您的应用程序有长期目标——我说的是几年甚至几十年——我会说去统一实现 PUT 和 PATCH 方法首先建议.如果您更喜欢简单的方法，请在 POST 中使用您或他的想法.

Do you know any "best practice" to design a REST method to alter the order of a small collection?

I have a collection exposed at "GET /api/v1/items". This endpoint returns a JSON array and every item has a unique id.

I was thinking on create "PATCH /api/v1/items" and send an array of ids with the new order. But I wonder if there is any alternative or design pattern to accomplish this task properly.

解决方案

Following the REST Uniform Interface constraint, the HTTP PUT and PATCH methods have to stick to the standard semantics, so you can do that with either one in the following way:

With PUT, clients can upload a whole new representation with the order they want. They will request GET /api/v1/items, change the order as they need, and submit it back with PUT /api/v1/items.

With PATCH, clients can send a diff document which performs the order change as they need. You can use a format like json-patch and clients perform the change with the move operation and array paths.

Be aware that neither of these are design patterns or best practices. They are simply how the PUT and PATCH methods are supposed to work. Ideally, this should work on any RESTful application implementing the GET, PUT and PATCH methods correctly for the resource at that URI, and that's the beauty of REST. If you do it the right way, you only have to do it once and clients can generalize for everyone. For instance, a client can choose to do it the PUT way with small collections, and the PATCH way for larger ones.

Both your idea to use PATCH with an id array, and the answerfrom @dit suggesting to do it with PUT aren't really RESTful because they are breaking up with the standard semantics: yours for not using a delta format, his for doing partial updates with PUT. However, both those options can be RESTful if done with POST. POST is the method to go for any action that isn't standardized by the HTTP protocol, so you can do anything you want with it, but you have to document how exactly to do it.

So, it's up to you. If you are concerned at all with being RESTful and your application has long term goals -- I'm talking years or even decades -- I'd say to go for a uniform implementation of the PUT and PATCH methods as suggested first. If you prefer a simple approach, use yours or dit's idea with POST.

这篇关于使用 REST API 更改数组/集合顺序的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！