Как мне реализовать глагол COUNT в моем веб-сервисе RESTful?

Я написал веб-службу RESTful, которая поддерживает стандартные операции CRUD, и которая может возвращать набор объектов, соответствующих определенным критериям (глагол SEARCH), но я хотел бы добавить глагол COUNT более высокого порядка, поэтому клиенты могут подсчитывать ресурсы, соответствующие критериям поиска, без необходимости их извлечения.

Несколько вариантов, которые возникают у меня:

Игнорирование спецификации HTTP и возврат количества объектов в тело ответа запроса HEAD.
Дублирование логики глагола SEARCH, но выполнение запроса HEAD вместо запроса GET. Затем сервер будет кодировать количество объектов в заголовке ответа.
Определение нового метода HTTP, COUNT, который возвращает количество объектов в теле ответа.

Я бы предпочел API первого подхода, но я должен использовать этот параметр, потому что он не соответствует требованиям. Второй подход кажется наиболее семантически правильным, но API не очень удобен: клиентам придется иметь дело с заголовками ответов, когда большую часть времени они хотят сделать что-то легкое, как response.count. Поэтому я склоняюсь к третьему подходу, но меня беспокоят потенциальные проблемы, связанные с определением нового метода HTTP.

Что бы вы сделали?

Ответ 1

Основная цель отдыха - определить набор ресурсов, с которыми вы взаимодействуете, используя хорошо определенные глаголы. Таким образом, вы должны избегать определения собственных глаголов. Количество ресурсов следует рассматривать как другой ресурс с собственным ури, который вы можете просто получить. Например:

GET resources?crit1=val1&crit2=val2

возвращает список ресурсов и

GET resources/count?crit1=val1&crit2=val2

Другой вариант - использовать conneg: например. Accept: text/uri-list возвращает список ресурсов, а Accept: text/plain возвращает только число

Ответ 2

Вы можете использовать HEAD без нарушения спецификации HTTP, и вы можете указать счет, используя заголовок HTTP Range в ответе:

HEAD /resource/?search=lorem

Отклик от службы, предполагая, что вы возвращаете первые 20 результатов по умолчанию:

...
Content-Range: resources 0-20/12345
...

Таким образом вы передаете количество ресурсов клиенту в заголовке ответного сообщения без необходимости возвращать тело сообщения.

Update:
Решение, предложенное Янник Лойзау, будет работать нормально. Просто хотел предоставить еще один альтернативный подход, который можно использовать для достижения того, что вам нужно, без необходимости определять новый ресурс глагола.

Вы можете использовать GET и добавить счет в тело сообщения. Затем, если вы API-интерфейс позволяет клиентам запрашивать ряд результатов, вы можете использовать это, чтобы ограничить размер тела сообщения до минимума (поскольку вам нужен только подсчет). Один из способов сделать это - запросить пустой диапазон (от 0 до 0), например:

GET /resource/?search=lorem&range=0,0

Затем служба может ответить следующим образом, указывая, что в результирующем наборе имеется 1234 соответствующих ресурсов:

<?xml version="1.0" encoding="UTF-8" ?>
<resources range="0-0/1234" />

Ответ 3

Игнорирование спецификации HTTP и возврат количества объектов в тело ответа запроса HEAD.

ИМХО, это очень плохая идея. Это может не работать просто потому, что у вас могут быть посредники, которые не игнорируют спецификацию HTTP.

Определение нового метода HTTP, COUNT, который возвращает количество объектов в теле ответа.

С этим подходом нет проблем. HTTP расширяется, и вы можете определить свои собственные глаголы. Некоторые брандмауэры запрещают это, но обычно они также запрещают заголовок POST и DELETE, а широко распространенный заголовок X-HTTP-Method-Override.

Еще одна опция, чтобы добавить параметр запроса к вашему URL-адресу, например:? countOnly = true