api - Media types for returning single item and collection of items

Question

I'm developing an API for returning either a single product or a collection of products, so will have endpoints like http://api.company.com/products/ and http://api.company.com/products/1/ that return data in the following structures:

// http://api.company.com/products/1/
{
    Id: 1
    Name: "Product 1"
}

// http://api.company.com/products/
[
    {
        Id: 1,
        Name: "Product 1"
    },
    {
        Id: 2,
        Name: "Product 2"
    }
]

I'm currently using the following media types in the Accept header, respectively:

application/vnd.company.product-v1.0+json // single product
application/vnd.company.products-v1.0+json // collection of products

Now it doesn't seem ideal to have two media types with "product" and "products" as I can see that leading to some confusion, but they do return different structures of data. So I'm wondering if there's any kind of API standard here that dictates whether you should only use one media type for both or not?

Answer 1

我没有指向“REST API 标准”的链接，该链接指示您的建议是否可以接受。但是，在我必须处理的许多 REST API 中，我还没有看到像您提议的那样使用接受标头的 API。

如果您稍后允许 GET /products 上的标志包含有关产品的不同级别的详细信息，会发生什么？您将需要不同的 Accept 标头值（例如 application/vnd.company.products-details-v1.0+json vs application/vnd.company.products-min-v1.0+json）

我相信你最好只使用一个 Accept 标头值。