Как следует исключать исключения из API RESTful для получения результатов?

Question

Мы разрабатываем API RESTful для возврата коллекций документов. Наша первоначальная реализация использует коды состояния HTTP, чтобы указать, не может ли выполнить запрос. Это, по-видимому, широко распространенная передовая практика (см., Например, here).

Мы недавно столкнулись с проблемой, когда пользователь извлекал 1000 документов. Одно из попыток поиска документов не удалось, и таким образом мы вернули код состояния HTTP 500.

Альтернативой может быть возврат кода состояния HTTP 200 с полезной нагрузкой, содержащей 999 документов, которые мы смогли получить, а затем сборка ошибок, указывающая ту, которая не удалась.

Является ли этот альтернативный подход нарушением принципов RESTful? Как следует справляться с этой ситуацией? Существуют ли какие-либо варианты помимо этих двух подходов?

Answer 1

Да, я думаю, что это вполне приемлемо, если вы документируете, что данные, которые вы возвращаете, могут содержать коллекцию «ошибок». Это означает, что любой семантический медиа-тип, который вы используете для описания этой коллекции документов, должен иметь документацию, которая описывает, как должна выглядеть коллекция документов, и как должна выглядеть коллекция ошибок. Затем клиент может решить, что делать с этой информацией.

Например, если вы возвращаете это как JSON (просто пример), вы можете иметь тип носителя, как application/json+documents или что-то, что может выглядеть следующим образом:

{ data : { 
    documents: [ ... ], //document objects 
    errors: [ ... ] //error objects 
} 

Вы бы тогда документацию описывает, как выглядят документы, и как выглядят ошибки. В действительно RESTful API это медиа-типы, которые документированы, а не вызовы, потому что в действительно RESTful API существует только одна конечная точка, а все остальное «обнаружено» через эту начальную конечную точку в сочетании с семантическими медиа-типами. Поэтому, пока вы документируете, что ошибки возможны, и вы описываете формат, в котором будут доставлены ошибки, вы должны быть в порядке.

Это также не является «исключительным» условием, так как кажется, что в вашем случае это возможно, что клиент может не получить все документы. Следовательно, это нормально, чтобы сообщить клиенту об этом факте.

Answer 2

Существует строка, которую вы иногда должны пересекать в уникальной ситуации, такой как: с участием пользователя.

Неразумно уведомить пользователя о том, что полезная нагрузка слишком велика и вернуть внутреннюю ошибку сервера.