Что вернуть в GET-методах RESTful API?

Question

Я относительно новичок в REST, и у меня был вопрос с самого начала.

Я перехожу к сути, скажем, у меня есть система электронной коммерции, поэтому у меня есть несколько «продуктов», у меня также есть этот ресурс: /api/products/1234 в моем веб-интерфейсе, и я отправляю ему GET HTTP-запрос ,

Что он должен вернуть? Если он возвращает всю сущность, включая все свойства, это не подходит в ситуациях, когда мне нужны только некоторые из этих свойств, а другие будут бесполезны. Например, в некоторых случаях мне просто нужны «Заголовок» и «Цена», поэтому другие свойства мне не нужны, это просто накладные расходы.

Как с этим справиться?

Заранее спасибо.

Answer 1

Помните, что /api/products/1234 идентифицирует ресурс , а не сущность . Ваш API может иметь много разных ресурсов, описывающих одну и ту же сущность. См. Доклад Джима Уэббера ОТДЫХ: DDD в целом .

(Также обратите внимание, что существует компромисс, поскольку каждый ресурс будет иметь свою собственную запись в кэше - это может быть неудобно, если клиент изменяет один ресурс, а затем видит устаревшую копию другого ресурса, описывающего ту же сущность).

Если вы используете другой подход к ресурсам, вы можете использовать любые варианты написания в URI, которые вам нравятся. Строка запроса - это обычный выбор, или расширение файла в сегменте пути, или даже создание отдельного сегмента пути. Насколько я могу судить, единственное реальное различие между вариантами выбора заключается в том, имеет ли относительное разрешение (RFC 3986) какое-либо значение в вашем случае использования.

Что он должен вернуть?

Распространенным выбором является использование шаблона DataTransferObject . Фаулер пишет

Когда вы работаете с удаленным интерфейсом, таким как Remote Facade (388), каждый его вызов обходится дорого. В результате вам нужно уменьшить количество вызовов, а это значит, что вам нужно передавать больше данных с каждым вызовом. Один из способов сделать это - использовать множество параметров. Тем не менее, это часто неудобно для программирования - действительно, это часто невозможно с такими языками, как Java, которые возвращают только одно значение.

Решение заключается в создании объекта передачи данных, который может содержать все данные для вызова.

Поскольку REST «спроектирован так, чтобы быть эффективным для передачи крупномасштабных гипермедиа данных» ( Fielding ), подход является подходящим.

Answer 2

Я могу думать о двух способах справиться с этим.

Пользовательский тип носителя

Вы можете использовать один из следующих (или обоих) типов мультимедиа для получения полного представления продукта:

GET /api/products/1 HTTP/1.1
Host: example.com
Accept: application/json

GET /api/products/1 HTTP/1.1
Host: example.com
Accept: application/vnd.company.full+json

И следующий тип носителя для получения только краткого представления продукта:

GET /api/products/1 HTTP/1.1
Host: example.com
Accept: application/vnd.company.short+json

Параметр строки запроса

Кроме того, вы можете поддержать выбор полей для извлечения с параметром строки запроса.

Используйте следующее, чтобы получить полное представление о продукте:

GET /api/products/1 HTTP/1.1
Host: example.com
Accept: application/json

И следующее, чтобы получить только название и цену продукта:

GET /api/products/1?fields=name,price HTTP/1.1
Host: example.com
Accept: application/json

Для удобства, несмотря на перечисленные поля, вы всегда можете вернуть идентификатор продукта.

---

Описанные выше подходы также могут быть применены к коллекциям ресурсов, таким как /api/products.

Как указал Эверт в комментариях, ", возможно, стоило бы исследовать, действительно ли отправка всего в любом случае приводит к снижению производительности или пропускной способности. Иногда бывает более приятным иметь более точные модели для ясности, если нет значительных затрат. «

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