c# - 如何设计用于批量插入和更新的 Restful API？

Question

我有一个 Web API 应用程序，我使用下面的 url 进行批量(数十或数百)插入和更新，它们只返回 OK 或 Failed。

POST api/v1/products

映射到我的操作:

public HttpResponseMessage PostProducts(PostProductsRequest request)
{

...
}

PostProductsRequest 对象包含 List 类型的 Products 属性。

如果某个属性存在 Id 属性，我会更新它，否则它会指示插入。

但我只是想知道我是否应该只将 Post 用于批量插入而将 Put 用于批量更新，不确定。每种方法的最佳实践和优势是什么？

如何设计用于批量插入和更新的 Restful API？

Answer 1

可以使用任何一种方法，具体取决于您的要求，但这并不意味着它们没有显着差异。 HTTP 方法不是 CRUD。 PUT 或 POST 不是创建和更新，反之亦然。

PUT 完全 用提供的实体替换给定 URI 处的资源，因此它可用于创建和更新，但前提是它包含完整表示。在 PUT 之后立即发出的 GET 请求应该返回相同的资源。表示可能完全相同，尽管服务可以添加 PUT 表示中缺少的默认值。

POST 告诉服务器所提供的实体从属于给定 URI 的资源，并且他们就应该如何处理达成了一致。它可能是任何东西，创建、更新、HTTP 本身未标准化的任何操作。

考虑到这一点，只有在替换由 URI 标识的整个集合时，使用 PUT 进行的批量插入或更新才是 RESTful。这不一定是与该媒体类型关联的整个收藏。 URI 可以有一个对数据集进行切片的查询字符串，并且您仅对该切片执行批量操作。

例如，如果您有以下集合资源:

GET /api/products

代表:

{'products': [product1, product2, product3]}

如果您想再添加三个产品，使用 PUT 的批量操作必须将您的新产品附加到现有产品并将整个集合发回:

PUT /api/products

{'products': [product1, product2, product3, product4, product5, product6]}

但是，如果你有一个过滤器约束，你可以应用到 /api/products ，它会在上面的 GET 上返回一个空集合，那么只用新的 PUT 就可以了产品到该过滤资源。例如，假设上面的产品可以按合作伙伴属性过滤，它们有合作伙伴 x，而您要为合作伙伴 y 添加:

在这种情况下，您可以这样做:

PUT /api/products?partner=y

{'products': [product4, product5, product6]}

然后 GET/api/products 返回:

{'products': [product1, product2, product3, product4, product5, product6]}

只要 GET/api/products?partner=x 返回:

{'products': [product1, product2, product3]}

GET/api/products?partner=y 返回:

{'products': [product4, product5, product6]}

这可能看起来很复杂，有时看起来使用 POST 而不是 PUT 更好，但请记住，上面的整个操作是标准化的。它完全按照预期的方式使用 PUT。使用 POST 的操作可以更直接，但它们不是标准化的，您必须为其设计和记录您自己的语法。