JSON-API设计

Question

假设我有不同类型的对象-- House和Car。现在我想补充一些评论。

有什么更好的练习吗？具有端点：

/api/house/:houseId/comments

/api/car/:carId/comments

或用于注释的通用api，如：

/api/comments/:generalId

Answer 1

对于我来说，产品类型是实现细节。为了成为REST风格，我将使用

/api/product/productID

此端点支持GET (获取给定产品)、POST (更新给定产品)、删除

/api/product/

这个端点将支持GET (获取所有产品)、PUT (创建新产品)

/api/product/productID/comments/commentID

此端点将支持get(给定产品的get给定注释)和POST (更新给定的注释)、delete(删除给定的注释)。在这种情况下，commentID可能仅在每个资源上是唯一的，而不是全局的。

/api/product/productID/comments

此端点将支持GET (获取产品的所有注释)和PUT(创建新注释)、DELETE (删除产品的所有注释)。

api/comments/commentId

这个资源(使用GET、POST、DELETE操作)也很好。但它需要全球唯一的commentId。如果您需要在不了解productId的情况下管理单独的注释，请随时公开这样的端点。这不违反休息。

在这个API设计中，我们为每个产品和注释提供了独立的资源。我们还拥有所有产品的资源，以及给定产品的所有评论的资源。每个资源都可以支持GET、POST、PUT、DELETE。您可以省略一些操作(例如，当不支持编辑注释时，不要在/api/product/[productID]/comments/[commentID]上公开/api/product/[productID]/comments/[commentID])。

编辑:正如@lospejos评论中所建议的那样，您可以使用复数形式(产品、注释)。无论哪种方式，您的API都是REST风格的，每个post/comment都是单独的资源。