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

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

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

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

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


api rest api-design restful-url
person Joe Alfano    schedule 16.04.2013    source источник

Ответы (2)


arrow_upward
2
arrow_downward

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

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

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

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

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

person Vivin Paliath    schedule 16.04.2013
comment
Спасибо Вивин за вклад. Так что я предполагаю, что возможная разделительная линия заключается в том, считается ли ситуация исключительной или нет. Если это так, то должен быть возвращен статус HTTP 500. Если ситуация не является исключением и можно ожидать, что она будет происходить регулярно в рамках нормального использования API, то, возможно, более подходящим вариантом является HTTP 200, отправляющий информацию об ошибке в (хорошо задокументированном!) Содержимом полезной нагрузки. - person Joe Alfano; 16.04.2013
comment
@JoeAlfano Верно. Если это фактическое исключение, от которого пользователь не может действительно восстановиться, тогда подойдет HTTP 500. В противном случае вы можете предоставить любые частичные данные, которые у вас есть, вместе с ошибками, и пользователь может решить, как с этим справиться. - person Vivin Paliath; 17.04.2013

arrow_upward
1
arrow_downward

Есть черта, которую иногда приходится переходить в такой уникальной ситуации: вовлечение пользователя.

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

person jakenberg    schedule 16.04.2013