Типы медиа для возврата одного элемента и коллекции элементов

Question

Я разрабатываю API для возврата одного продукта или набора продуктов, поэтому у меня будут конечные точки, такие как http://api.company.com/products/ и http://api.company.com/products/1/ которые возвращают данные в следующих структурах:

// 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"
    }
]

В настоящее время я использую следующие типы мультимедиа в заголовке Accept соответственно:

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

Теперь не кажется идеальным иметь два типа медиа с "product" а также "products" как я вижу, это приводит к некоторой путанице, но они возвращают различные структуры данных. Поэтому мне интересно, есть ли здесь какой-либо стандарт API, который определяет, следует ли использовать только один тип мультимедиа для обоих или нет?

Answer 1

У меня нет ссылки на "Стандарт API REST", который определяет, является ли то, что вы предлагаете, приемлемым или нет. Однако из многих REST API, с которыми мне приходилось иметь дело, я не видел ни одного, который бы использовал заголовок accept, как вы предлагаете.

Что произойдет, если вы позже разрешите флаги на GET /products включать разные уровни подробностей о продуктах? Вам потребуются другие значения заголовка Accept (пример application/vnd.company.products-details-v1.0+json против application/vnd.company.products-min-v1.0+json)

Я считаю, что вам лучше всего с одним значением заголовка Accept.