REST-интерфейс для нахождения среднего

Question

Предположим, я хочу создать интерфейс REST, чтобы найти среднее из списка чисел. Предположим, что числа представлены по одному. Как бы вы это сделали?

1. POST номер к http://site.com/api/average
2. Если это первое число, будет возвращен хеш
3. POST номер к http://site.com/api/average/hash ....
4. GET http://site.com/api/average/hash, чтобы найти среднее значение
5. УДАЛИТЬ http://site.com/api/average/hash, поскольку оно нам больше не нужно

Это правильный способ сделать это? Какие-либо предложения?

Answer 1

Имеет смысл рассматривать список чисел как ресурс. Предположим, что URL ресурса каждого списка равен /list/{id}, где {id} является заполнителем для идентификатора списка. Тогда:

1. POST /list создает новый список, сервер генерирует идентификатор списка (или «хэш») и указывает URL-адрес /list/{id} в заголовке Location ответа.
2. POST /list/{id} добавляет номер в список
3. GET /list/{id}/average возвращает среднее значение
4. DELETE /list/{id} удаляет список.

Альтернативой GET /list/{id}/average будет GET /list/{id} для возврата списка в виде структурированных данных, например, XML, который включает в себя среднее значение как сгенерированное свойство.

Answer 2

Вы не можете просто вернуть хеш или идентификатор, вы должны вернуть URI или шаблон URI плюс значения полей. Единственный URI, который может быть частью вашего API - это точка входа, в противном случае ваш API не является REST.

Answer 3

То, о чем вы говорите, - это преобразование представления запроса (списка номеров) в состояние без сохранения состояния в представление ответа (одно число).

Позволяет классифицировать ваш ресурс:

• Без сохранения состояния - запрос без сохранения состояния, но и ресурс. Он должен быть в состоянии принять ваш запрос, обработать его и вернуть ответ без сохранения какого-либо внутреннего состояния. Дальнейшее обсуждение ниже.
• Вряд ли можно кешировать - я предполагаю, что ваши списки чисел никогда / редко бывают идентичны.
• Идемпотент - Запросы не имеют побочных эффектов. Это потому, что ресурс не имеет состояния.

Теперь давайте рассмотрим различные методы HTTP:

• GET - Получает состояние ресурса. Поскольку у вашего ресурса нет состояния, он не подходит для вашей ситуации. (идемпотент, кешируется)
• УДАЛИТЬ - Удаляет ресурс или очищает его состояние. Также не подходит для вашей ситуации. (не идемпотентный, не кешируемый)
• PUT - используется для установки состояния ресурса (или создания его, если он не существует). (идемпотент, не кешируется)
• POST - используется для обработки запросов, которые могут изменять или не изменять состояние ресурса. Может создавать другие ресурсы. (без гарантии идемпотентности - зависит от того, является ли ресурс состоящим из состояния или без состояния, не кешируется)

Как вы видите в других ответах, POST наиболее часто используется как синоним 'create'. Хотя это нормально, POST не ограничивается просто «созданием» в REST. Марк Бейкер хорошо объясняет это здесь: http://www.markbaker.ca/2001/09/draft-baker-http-resource-state-model-01.txt (Раздел 3.1.4).

Хотя POST не имеет идеального семантического отображения для вашей проблемы, это лучший из всех методов HTTP для того, что вы пытаетесь сделать. Это также приводит к простому, не зависящему от состояния и масштабируемому решению, которое является точкой REST.

В итоге, ответ на ваш вопрос:

• Метод: POST
• Запрос: представление списка номеров
• Ответ: представление одного числа (среднее по списку)

Хотя это может выглядеть как вызов веб-службы в стиле SOAP, это не так. Не позволяйте вашей интуитивной реакции на SOAP использовать ваш метод POST и накладывать на него ненужные ограничения.

KISS (будь проще, глупый).

Answer 4

Чтобы максимизировать REST-философию, я бы сделал следующее

Выполните PUT, чтобы указать новую структуру, которая будет генерировать хеш, то есть , а не на основе переданного числа. Просто "случайный" хеш. Затем каждый последующий пост будет включать в себя id-хэш с возвращенным результатом хеша отправленных номеров. Затем, когда вы получаете get, вы можете кэшировать результаты.

1. PUT    /api/average/{number} //return id-hash
2. POST   /api/average/{id-hash}/{number} // return average-hash
3. GET    /api/average/{average-hash}
4. DELETE /api/average/{id-hash}

Затем вы можете кэшировать получение среднего хэша, даже если вы можете получить результат другим способом или разные серверы получают такое же среднее значение.