Служба REST возвращает коллекцию XML-документов

Question

Мы пишем сервис REST для запроса файлов PDF. Потребитель услуг хочет получить метаданные для этих PDF-файлов, а не фактический PDF-файл. Метаданные для этого хранятся в виде документа XML, один документ XML для каждого ресурса PDF. Они являются ресурсом, а метаданные ресурса - совершенно разными файлами.

Как должен выглядеть ответ на запрос?

Обычно мы используем JSON для тел запросов / ответов. Должно ли тело ответа быть объектом JSON, содержащим коллекцию URL-адресов, где каждый URL-адрес связан с документом метаданных? Это кажется довольно чистым, но вызывает много ненужного сетевого трафика, потому что потребитель должен отправить запрос GET для каждого документа метаданных.

Должен ли XML документов метаданных быть встроен в объект JSON тела ответа? (чёрт!)

Есть ли решение одновременно чистое и эффективное?

Answer 1

Основываясь на некоторых поясняющих комментариях, я собираюсь предложить вам не писать "RESTful" API. Вам не нужен один. У вас нет объектов, с которыми вам нужно взаимодействовать каким-либо сложным образом. У вас нет состояния, на которое нужно воздействовать (REST означает передачу состояния представления).

Вам просто нужен HTTP API. Просто верните XML-файл. Вы также можете предоставить конечную точку для архивирования нескольких документов XML, если хотите.

Сделайте что-то вроде этого:

• /api/host/123 - загрузите файл PDF (Content-Type: application/pdf) - Вы не сказали, есть ли у вас конечная точка для PDF-файлов, но если она вам нужна, я бы ее структурировал.
• /api/host/123/metadata - загрузите метаданные XML (Content-Type: text/xml)
• /api/host/bulk_metadata - загрузить ZIP-файл метаданных для идентификаторов файлов, перечисленных в параметре POST (Content-Type: application/zip)

Используйте Content-Disposition: attachment; filename="{filename}.{pdf|xml|zip}", чтобы указать браузерам загружать контент вдиск, а не отображать его в строке.