这会被认为是糟糕的 RESTFul 设计吗？

Posted 2023-04-11

【中文标题】这会被认为是糟糕的 RESTFul 设计吗？

【英文标题】：Will this be considered as bad RESTFul design?

【发布时间】：2017-07-02 18:39:58

【问题描述】：

我在 Spring 中首次设计 API，我有以下用例：

获取所有产品。 按 ID 获取产品。

现在，我所做的是，我为此制作了一个 API，

@Path("/products")
public interface ProductResource 

    @GET
    @ApiOperation(value = "Gets all the products by criteria")
    Response getProductsByCriteria(@Context UriInfo uriInfo);

我正在做的是，我在查询参数中获取 ID。如果它的值为null，我将调用该方法（在服务层）返回所有产品，否则我将调用该方法根据其id（进入查询参数）返回特定产品。

我只是想知道，这是一个糟糕的 RESTFul 设计吗？我是否应该使用两个单独的 API 来根据他们的 ID 获取产品并获取所有产品？

【问题讨论】：

Should I instead have two seperate API's for getting products based on their ID's and for getting all the productS? 绝对是的，你应该这样做。这样，您的服务将更有凝聚力，并且任何查看您的代码的人都更容易理解它。

【参考方案1】：

你绝对应该有

GET /products - 返回所有产品列表 GET /products/:id - 如果找不到产品，则返回单个产品或 404

通过这种方式，它更易于阅读，并且与您在 Internet 上找到的其他优质 API 保持一致。

【参考方案2】：

我建议有单独的端点：

GET /products 适用于所有产品 GET /products/productId 用于通过特定 ID 获取产品，该 ID 将作为 PathParam 传递。通过这种方式，您可以使用其他端点来操作产品数据，例如PUT /products/productId 或DELETE /products/productId。如果未找到产品，他们将返回 HTTP 状态 NOT FOUND (404)。

QueryParam更适合按某些特征过滤产品，例如GET /products?color=red。

【参考方案3】：

通过混合 getAll 和 getById，您错过了重要的一点：API 的调用者无法知道 productId 是否存在。 通常，您会在获取不存在的产品 ID 时返回 404。

所以回答你的问题：是的，这是一个 Restful 设计错误。