Коды ошибок и статусы

Пример кода статуса в заголовке curl

Коды статусов не отображаются в тебе ответа. Они содержатся в хэдере, который может быть не видим по умолчанию.

Заголовок ответа выглядит следующим образом:

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

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

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

Где перечислять HTTP-ответ и коды ошибок

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

С другой стороны, если какие-то коды состояния и ошибок больше подходят к определенным конечным точкам, чем другие, имеет смысл вывести такие коды состояния и ошибок на страницы с описаниями конечных точек.

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

Где взять коды ошибок и статусы

Коды состояния и ошибок могут быть неочевидны в документации API. Вероятно, придется попросить разработчиков предоставить список всех кодов состояния и ошибок, которые уникальны для API. Иногда разработчики хардкодят коды состояния и ошибок непосредственно в программном коде, и у них нет простых способов передать полный список (что также затрудняет локализацию).

В результате может потребоваться танцы с бубнами, чтобы найти все коды. В частности, возможно придется сломать API, чтобы увидеть все возможные коды ошибок. Например, если превысить ограничение скорости для определенного запроса, API может вернуть специальную ошибку или код состояния. Такой пользовательский код обязательно нужно задокументировать. В разделе устранения неполадок в API можно специально разместить примеры получения кодов ошибок.

Как перечислять коды ошибок

Коды статусов и ошибок можно привести в виде списка определений или таблицы, например так:

Коды состояния и ошибок помогают в устранении неполадок

Коды состояния и ошибок особенно полезны при устранения неполадок. Таким образом, можно рассматривать коды ошибок как дополнение к разделу по устранению неполадок.

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

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

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

Примеры кодов статусов и ошибок

Ниже приведены несколько вариантов разделов с кодами статусов и ошибок.

Context. io

Clearbit не только документирует стандартные коды состояния, но также описывает уникальные параметры, возвращаемые их API. Большинство разработчиков, вероятно, знакомы с кодами 200, 400 и 500, поэтому эти коды не требуют много пояснений. Но если API имеет уникальные коды, описывать их нужно адекватно и подробно.

Twitter

В Twitter не только описывается код и состояние, но также предоставляется полезная информация по устранению неполадок, потенциально помогая в устранении ошибок. Например, про ошибку 500 не просто сказано, что статус относится к неработающей службе, но и есть объяснение: «Обычно это временная ошибка, например, в ситуации высокой нагрузки или если у конечной точки временно возникают проблемы. Посетите форумы разработчиков на случай, если у других возникнут аналогичные проблемы, или повторите попытку позже».

Mailchimp

Mailchimp предоставляет удобочитаемые и понятные описания сообщений об ошибке. Например, в ошибке 403 вместо того, чтобы просто написать «Запрещено», Mailchimp объясняет причины, по которым можно получить ошибку запрещенного кода. У Mailchimp существует несколько типов ошибок 403. Запрос может быть запрещен из-за отключенной учетной записи пользователя или запроса, направленного не в тот центр обработки данных. В случае ошибки «WrongDataCenter» Mailchimp отмечает, что «она часто связана с неправильно настроенными библиотеками» и ссылается на дополнительную информацию о центрах обработки данных. Такой тип документации кода ошибки очень полезен для пользователей.

Flickr

В Flickr раздел «Коды ответов» встроен в описание каждой адресной темы API. Описания ошибок выглядят короткими. Хотя встраивание кодов ответов в каждую тему делает коды ошибок более заметными, в некоторых случаях такой подход менее полезен. Поскольку он встроен в каждую тему API, описания кодов ошибок должны быть краткими, иначе их содержимое будет перегружено информацией о запросе конечной точки.

Напротив, отдельная страница с перечнем кодов ошибок позволяет более подробно раскрывать каждый код, не вытесняя другую документацию. Отдельная страница также уменьшает избыточность и увеличивает объем информации.

?‍? Практическое занятие: Коды статусов и ошибок

В своем найденном опен-сорс проекте найдем информацию о кодах статусов и ошибок. Ответим на следующие вопросы:

REST страсти по 200

Давно я хотел написать эту статью. Все думал — с какой стороны зайти правильнее? Но, вдруг, недавно, на Хабре появилась подобная статья, которая вызвала бурю в стакане. Больше всего меня удивил тот факт, что статью начали вбивать в минуса, хотя она даже не декларировала что-то, а скорее поднимала вопрос об использовании кодов ответа web-сервера в REST. Дебаты разгорелись жаркие. А апофеозом стало то, что статья ушла в черновики… килобайты комментариев, мнений и т. д. просто исчезли. Многие стали кармо-жертвами, считай, ни за что

В общем, именно судьба той статьи побудила меня написать эту. И я очень надеюсь, что она будет полезна и прояснит многое.

Предупреждаю, все ниже написанное является реальным опытом, а не когнитивной эквилибристикой. И так, погнали.

Первым делом нужно очень четко разделить слои. Слой транспорта — http. Ну и собственно REST. Это фундаментально важная вещь в принятии всего и “себя” в нем. Давайте сначала поговорим только о http.

Я использовал термин “слой транспорта”. И я не оговорился. Все дело в том, что сам http реализует функции транспортировки запросов к серверу и контента к клиенту независимо от tcp/ip. Да, он базируется на tcp/ip. И вроде, нужно считать именно его транспортным. Но, нет. И вот почему — сокет-соединения не являются прямыми, т. е. это не соединение клиент-сервер. Как http запрос, так и http ответ могут пройти длинный путь через уйму сервисов. Могут быть агрегированы или напротив декомпозированы. Могут кэшироваться, могут модифицироваться.

Т. е. у http запроса как и http ответа есть свой маршрут. И он не зависит ни от конечного бэка, ни от конечного фронта. Прошу на это обратить особое внимание.

Маршруты http не являются статическими. Они могут быть очень сложными. Например, если в инфраструктуру встроен балансировщик, полученные запросы он может отправить на любую из нод бэка. При этом, сам бэк может реализовывать собственную стратегию работы с запросами. Часть из них пойдет на микросервисы напрямую, часть будет обработана самим web-сервером, часть дополнена и передана кому-то еще, а часть выдана из кэша и т. п. Так работает Интернет. Ничего нового.

И тут важно понять — зачем нам коды ответов? Все дело в том, что вся вышеописанная модель принимает решения на их базе. Т. е. это коды, позволяющие принимать инфраструктурные и транспортные решения в ходе маршрутизации http.

К примеру, если балансировщик встретится с кодом ответа от бэка 503, при передаче запроса, он может принять это за основание считать, что нода временно недоступна. Отмечу, что в ответе с кодом 503 предусмотрен заголовок Retry-After. Получив из заголовка интервал для повторного опроса, балансировщик оставит ноду в покое на указанный срок и будет работать с доступными. Причем, подобные стратегии реализуются “из коробки” web-серверами.

Небольшой офтопик для глубины понимания — а если нода ответила 500? Что должен сделать балансировщик? Переключать на другую? И многие ответят — конечно, все 5xx основание для отключение ноды. И будут неправы. Код 500 это код неожиданной ошибки. Т. е. той, которая может больше никогда и не повториться. И главное, что переключение на другую ноду может ничего и не изменить. Т. е. мы просто отключаем ноды без малейшей пользы.

В случае с 500 нам на помощь приходит статистика. Локальный WEB-сервер ноды, может переводить саму ноду в статус недоступности при большом количестве ответов 500. В этом случае, балансировщик обратившись на эту ноду, получит ответ 503 и не будет ее трогать. Результат тотже, но теперь, такое решение осмысленно и исключает “ложные” срабатывания.

Но и это еще не все. В такой ситуации мониторинг позволит админам подключиться к ситуации для обслуживания ноды. Т. е. мы получаем не просто реализацию высокодоступного сервиса, с балансировками и т. п., но еще и эффективный процесс поддержки.

И все это позволяют делать коды ответа сервера. Любая архитектура WEB-приложения должна начинаться с проектирования транспортного слоя. Надеюсь, сомнений в этом не осталось.

Задам риторический вопрос — что это такое? И что вы ответили себе на него? Не буду давать ссылки на очевидные пруфы, но скорее всего не совсем то, чем он является по сути Это лишь идеология, стиль. Некие соображения на тему — как лучше общаться с бэком. И не просто общаться, а общаться в WEB инфраструктуре. Т. е. на базе http. Со всеми теми “полезными штуками”, о которых я написал выше. Конечные решения по реализации вашего интерфейса остаются всегда за вами.

Вы задумывались почему не придуман отдельный транспорт для REST? Например, для websocket он есть. Да, он тоже начинается с http, но потом, после установки соединения, это вообще отдельная песня. Почему бы не сделать такую же для REST?

Ответ прост — а зачем? Есть прекрасный, уже готовый, выверенный протокол — http. Он хорошо масштабируется. Позволяет реализовывать сложные, высокодоступные сервисы, способные справляться с большой нагрузкой. Все, что нужно — ввести некие концептуальные правила, чтобы разработчики друг друга понимали.

Отсюда следует простой, очевидный вывод — все, что присуще http, присуще и REST. Это неотделимые сущности. Нет отдельного заголовка REST, нет даже намека на то, что REST это REST. Для любого сервера REST запрос ровно такой же, как и любой другой. Т. е. REST это только то, что у нас “в голове”.

Коды ответа http в REST

Давайте поговорим о том, каким же кодом должен отвечать ваш сервер на REST запрос? Лично мне кажется, что из всего выше написанного уже очевиден ответ, что т. к. REST не отличается от любого другого запроса, он должен быть подчинен ровно тем же правилам. Код ответа — неотъемлемая часть REST и он должен быть релевантен сути ответа. Т. е. если не найден объект по запросу, это 404, если клиент обратился с некорректным запросом 400 и т. д. Но, чаще всего, дебаты на сём не заканчиваются. Поэтому, продолжу и я.

Можно ли отвечать на всё кодом 200? А кто вам запретит? Пожалуйста… код 200 такой же код как и другие. Правда, в основе такого подхода лежит очень простой тезис — моя система идеальная, у нее не бывает ошибок. Если вы человек, который может создавать такие системы — этому можно только позавидовать!

Но скорее всего… она не идеальна. И ошибки все же случаются. А бывает, что они случаются по независящим от нас обстоятельствам. И тут типовым решением является создание собственной системы кодирования ошибок. Это плохо? Да, это плохо. Это супер-плохо. Давайте разбираться почему.

И так, принимая код 200 как единственно верный, мы берем на себя обязанности на разработку целого слоя (критического слоя) системы — обработку ошибок. Т. е. труд многих людей по разработке этого слоя отправляется в утиль. И начинается постройка своего “велосипеда”. Но эта мегастройка обречена на провал.

Начнем с кода. Если мы собираемся на все отвечать 200, нам самим придется обрабатывать ошибки. Классическим методом является try конструкции. Каждый сегмент кода мы оборачиваем дополнительным кодом. Обработчиками, которые что-то делают полезное. Например, что-то кладут в лог. Что-то важное. Что позволит локализовать ошибку. А если ошибка возникла не там где ее ожидали? Или если ошибка возникла в обработчике ошибки? Т. е. эта стратегия на уровне кода нерабочая априори. И в конце концов, обрабатывать ваши баги будет интерпретатор или платформа. ОС, наконец. Суть бага в том, что вы его не ждете. Не нужно его прятать, его нужно находить и фиксить. Поэтому, если на какие-то запросы REST ответит ошибкой 500 это нормально. И более того — правильно.

Давайте еще раз вернемся к вопросу — почему это правильно? Потому что:

7. Даже если вы очень сильно постараетесь избежать иных кодов ответа от сервера кроме как 200 на ваши запросы, вы не сможете это сделать. Вам может ответить на ваш запрос любой сервер посредник, совершенно любым кодом. И вы ДОЛЖНЫ будете такой ответ обработать корректно.

Итого, на логическом уровне борьба за код 200 бессмысленна.

Теперь давайте вернемся к инфраструктурному уровню. Очень часто слышу мнение — код 5xx не прикладного уровня, его нельзя отдавать бэком. Кхм, ну… тут есть противоречие в самом утверждении. Отдавать можно. Но код этот не прикладного уровня. Вот так вернее. Для понимания этого, предлагаю рассмотреть кейс:

И так, что вы должны ответить? Кому? Это проблема именно инфраструктурная и, именно, бэк столкнулся с ней. Конечно, нужно смело отвечать 503. Эти действия приведут к тому, что нода будет отключена балансировщиком на какое-то время. При этом, балансировщик при правильной настройке, не разрывая соединение с клиентом, отправит запрос в другую ноду. И… конечный клиент, с великой долей вероятности получил 200. А не кастомное описание ошибки, которая ему ничем не поможет.

Где и какой код использовать

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

Есть принятые стандарты. Их можно легко найти и, опять же, не буду очевидные пруфы приводить. Но, приведу неочевидный — developer. mozilla. org/ru/docs/Web/HTTP/Status
Почему его? Все дело в том, что обработчики кода могут вести себя по разному, в зависимости от реализации и контекста “понимания кода”. К примеру, в браузерах есть стратегия кеширования, завязанная на коды ответа. А в некоторых сервисах есть свои, кастомные коды. Например, CloudFlare.

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

Корни зла

Уже третий проект, в который я прихожу страдает кодом 200 в REST. Именно страдает. Другого слова нет. Если вы внимательно прочли всё до текущего момента, вы уже понимаете, что как только проект начинает расти, у него появляется потребность в развитии инфраструктуры, в ее устойчивости. Код 200 убивает все эти потуги на корню. И первое, что приходится делать — ломать стереотипы.

Корень зла, мне кажется лежит в том, что код 500, это первое, что web-разработчик встречает в своей профессиональной деятельности. Это, можно сказать, детская травма. И все его старания поначалу сводятся к тому, чтобы получить код 200.

Кстати, по какой-то причине, на этом же этапе развивается устойчивое мнение, что только ответы с кодом 200 могут быть снабжены телом. Конечно, это не так и с любым кодом может “приехать” любой ответ. Код это код. Тело это тело.

Далее, с развитием разработчика, у него возникают потребности в управлении багами собственного приложения. Но…, он не умеет пользоваться логами. Не умеет настраивать web-сервер. Он учится. И рождаются те самые «велики». Потому что, они ему доступны и он может их быстро сделать. Далее, на этот «велик» он монтирует новые колеса, усиливает раму и т. д. И этот велик становится его спутником на достаточно длительный промежуток времени, пока… пока у него не появляются реально сложные, многокомпонентные задачи. И тут, как говорится — вход в супермаркет с «великами» и на роликах запрещен.

REST API: что это такое простыми словами, примеры запросов, варианты использования сервиса, методы

В этой статье мы разберем оболочку REST API, расскажем, что это такое простыми словами, как работает система.

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

Что такое REST API

Так называют сокращение английской аббревиатуры, которая переводится как передача состояния представления. Web-службы, которые пользуются этой системой, применяют термин RESTful. Единого стандарта у нее нет — не протокол, а целый архитектурный стиль. Этим она отличается от многих аналогичных. При этом допустимо использовать XML, HTTP, JSON и URL.

Ее разработали еще в 2000 году, но с того момента она очень развилась и сейчас стала одной из самых популярных, отодвинув на задний план аналогичные.

Чтобы объяснить суть restful api для чайников, можно представить калькулятор на любом компьютере. Когда мы нажимаем на кнопки, желая получить расчеты, скрытые функции начинают взаимодействовать. А когда сервис получает результат, он выводит его на экран в виде готовой цифры в графическом интерфейсе.

Здесь архитектура работает аналогичным образом. При нажатии на кнопку выполняются разные операции, чтобы обработать и передать информацию. Они могут не просто получать данные из одной сети, а способны вызывать и обращаться к удаленным серверам, чтобы взять нужное у них.

В качестве примера стоит привести кнопку Facebook, которая умеет задействовать соцсеть, или видео на Youtube, его тоже запускает веб-версия API.

Как работает

В первую очередь стоит разобраться, как действует подход. Преимущества:

Суть оболочки заключается в паре действий, в зависимости от типа запроса. От работы сервера зависит функционал и способности архитектуры. Есть 4 основных вида в отношении информации:

В качестве пакета обычно отправляется JSON массив на указанный конкретный URL. Там срабатывает так называемая функция, а в зависимости от уже отправленных данных и текущего запроса начинается определенное действие.

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

Что такое API

Вокруг этого объяснения много споров, потому как он:

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

В его задачи входит представлять состояние передачи. Уже из названия становится понятно, как должно работать хорошо разработанный софт. Даже сеть страниц можно рассматривать, как машину состояний:

Протокол по типу концентрированного REST API, работающий по HTTP равно качественным веб-сервисам

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

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

Это вообще лучшая часть всего созданного в компьютерном мире. Так как они не зависят от языков, то могут совмещаться с самыми разными системами. Когда API документируется, то неважно, чем пользовались разработчики при его создании — Ruby это был, Java или Python или что-то принципиально другое. Все запросы высылаются через один и тот же HTTP, решения приходят таким же способом.

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

SOAP стоит отнести к предкам интерфейсов по типу REST API

Еще перед тем, как прикладное программирование нового поколения стало популярным и везде используемым, у него был аналог — SOAP. Он был максимально распространен. А чтобы понять разницу, стоит разобраться в истоках.

SOAP это протокол, который работает по заранее определенному стандарту. Ему для работы требуется XML, это определит формат, в котором будут отражаться входящие и исходящие запросы. Так как это стандартная вещь, подвид можно определить, если использовать файл WSDL — он помогает расшифровывать язык, на котором пишут веб-службы. Он определяет, есть ли атрибуты или какие-то расширенные элементы в передающихся сообщениях. Это машиночитаемая часть функционирования сети, поэтому пользуются им только сервера, которые действуют и общаются, чтобы облегчить связь.

Все сообщения внутри SOAP собираются в своеобразные «конвертики», в которых есть заголовок и основное тело. Все это «пакуется» при помощи заранее сформированной схемы по принципу XML.

Основная проблема этой системы в том, что формат, который используется для передачи, излишне тяжелый. Это вызывает серьезные проблемы в выполняемых сценариях на мобильных устройствах, задерживает загрузку, делает слишком медленной обработку. Там, где пропускная способность очень важна, эту схему не хочется использовать. Это одна из причин, которые стали поводом для разработки и создания rest сервиса.