我们应该在 REST API 的路径参数、查询参数或 JSON 请求中使用枚举常量吗？

Question

问题是关于 REST API 的最佳实践。

示例：我有一个以路径参数作为状态的 get API。

/api/{status}

现在，在代码中，状态被定义为一个枚举（Status）。状态值只能有 3 个（或一些有限的）可能值。

public enum Status {
    created,
    completed,
    cancelled
}

那么，我应该接受“状态”作为字符串还是枚举类型？

@Path("/api/{status}")
@GET
public Response get(@PathParam("status") String status) {}
// then I can check if it is a valid status

或者

@Path("/api/{status}")
@GET
public Response get(@PathParam("status") Status status) {}
// it will throw an exception if it is an invalid status

另外，我也想知道关于查询参数和 JSON 请求的最佳实践。

Answer 1

在 API 上使用枚举可以带来更好的设计。其原因与我们一般使用它们的原因相同。具有枚举的编程语言中的枚举与 OpenApi 规范https://swagger.io/docs/specification/data-models/enums/之间存在兼容性，因此我认为没有什么好的理由反对它们。