При современном развитии технологий часто приходится реализовывать взаимодействие различных программных систем через интернет. Большинство из них написаны на одном из популярных языков программирования и имеют стандартные библиотеки для работы по протоколу HTTP. Поэтому естественным образом возник и стал широко применяться подход проектирования API поверх HTTP.
Реализация API поверх HTTP не приводит к существенным дополнительным задержкам, помимо уже существующих и возникающих между аппаратным железом и интегрируемыми системами. А поскольку HTTP — протокол текстовый, это упрощает разработку небольших интегрируемых систем.
Серверная часть сообщает об ошибке двумя способами: при помощи кода состояния HTTP и в рамках проектируемого API.
Ответы сервер иногда записывает в заголовки, но наиболее распространённый вариант — размещение ответа в теле сообщения, которое может быть структурировано в формате JSON и XML.
Классы кодов состояния HTTP
Коды состояния HTTP — основной индикатор ошибок API. Это способ сервера сообщить пользователю, что он думает о его запросе. Написаны они в виде трёхзначных чисел, где первая цифра обобщает категорию, а остальные две показывают точный характер ошибки. Некоторые категории могут содержать до двадцати видов ошибок.
Краткий обзор классов кодов состояния HTTP:
-
1xx. Информационный — передаёт информацию на уровне протокола передачи.
-
2xx. Коды от 200 до 299 (включительно) означают, что вызов API прошёл успешно.
-
3хх. Категория ошибок, обозначающая перенаправление: для успешного завершения запроса необходимо перейти по другому адресу.
-
4xx. Ошибка клиента, когда сервер по какой-то причине не смог обработать отправленный пользователем API запрос.
-
5xx. Серверная ошибка, при которой появилось неожиданное условие, помешавшее корректному выполнению полученного запроса.
Распространённые ошибки API
Разберём часть наиболее распространённых ошибок API.
301, moved permanently
Обращение к документам, находящимся по другому URL-адресу, который указан в заголовке страницы, в поле Location. Однако не все браузеры могут обработать эту ошибку и показать новый адрес. Совместимость кодов HTTP с браузерами можно посмотреть здесь.
304, not modified
Клиентом запрошен документ, уже сохранённый в кеше на сервере, который не изменялся со времени своего предыдущего сохранения. В этой ситуации повторно такой документ не высылается и пользователь сможет пользоваться его локальной копией. Чтобы решить проблему, попробуйте убрать кеширование файлов на веб-сервере.
305, use proxy
Для получения запрошенных данных подключите прокси (по соображениям безопасности в некоторых регионах функция не поддерживается).
400, bad request error
Сервер не смог проанализировать запрос из-за ввода некорректного URL-адреса или неправильно составленного запроса. Если синтаксически всё оформлено верно и данные введены правильно, ищите ошибки в самом приложении.
401, bad request error
Ошибка API при аутентификации пользователя, вводе неправильного имени и пароля, а также при отсутствии права доступа. Если данные введены правильно, но вы всё ещё получаете сообщение об ошибке, обратитесь в техническую поддержку поставщика API.
403, bad request error
Ошибка показывает неспособность сервера обработать запрос пользователя из-за проблем с авторизацией или из-за других ограничений, установленных поставщиком API. Для устранения проблемы получите соответствующие разрешения для выполнения запросов к необходимым эндпоинтам API, проверьте корректность отправляемых данных и отсутствие внешних ограничений, способных блокировать к ним доступ.
404, not found error
Не найден запрошенный ресурс у поставщика API. Возможно, вы ввели неправильный URL-адрес или некорректно составили запрос. Чтобы устранить эту ошибку API, необходимо проверить правильность введённых данных и обратиться за помощью к поставщику услуг.
408, request timeout error
Неполучение ответа от пользователя в течение определённого периода времени, по окончании которого соединение прерывается. Чтобы устранить ошибку, проверьте правильность URL, подключение к интернету, настройки тайм-аута и перезагрузите страницу.
410, gone
Запрошенный ресурс не найден и нет возможности перенаправления. Ожидается, что пользователи очистят свой кеш и обновят ссылку на содержимое в запросе.
429, too many requests
Превышение лимита по числу запросов в обозначенный временной интервал.
431, request header fields too large
Сигнализирует о невозможности обработки запроса сервером ввиду превышения пользователем лимита по величине заголовка.
500, internal server error
Столкновение сервера с необычным условием, блокирующим выполнение сгенерированного запроса. Нередко подобного рода ошибка вызвана проблемой во внутренних системах поставщика API или некорректно составленного запроса. Убедитесь в правильности введённых параметров данных и обратитесь к поставщику API.
501, not implemented
Указывает на невозможность обработки пользовательского запроса из-за неподдерживаемого метода. Важно отметить, что сервер должен поддерживать методы GET и HEAD всегда, в остальных случаях клиент не увидит такого ответа.
502, bad gateway error
Получение прокси-сервером неприемлемого ответа от другого вышестоящего сервера. Возможные причины:
-
имя домена не преобразуется в правильный IP-адрес
-
сервер недоступен
-
соединение FireWire блокирует связь
Для устранения этой ошибки API проверьте корректность введения доменного имени и журналы брандмауэра, убедитесь в доступности вашего сервера.
503, service unavailable
Сервер не готов выполнить ваш запрос ввиду проведения технических работ или по причине избыточной нагрузки. Чтобы обеспечить более понятное взаимодействие с пользователем, рекомендуется предоставить информативную страницу с объяснением текущей ситуации.
Также для улучшения опыта включите HTTP-заголовок Retry-After, указывающий на ожидаемое время восстановления. Рекомендуется передавать заголовки сведений о кешировании, поскольку подобные временные ответы обычно не подлежат ему.
504, gateway timeouterror
Прокси-серверу не поступил ответ от другого, стоящего над ним сервера в течение обозначенного времени. Такая ситуация может произойти из-за проблем с интернет-подключением или по причине некорректно составленного запроса.
505, HTTP version not supported error
Не поддерживается запрошенная клиентом версия протокола. Чтобы решить проблему, обратитесь за помощью к поставщику API.
507, insufficient storage error
Сигнализирует о том, что для выполнения запроса API на сервере недостаточно места. Увеличьте размер хранилища, подключив более вместительный пакет хостинга. При избыточном трафике страниц оптимизируйте репозитории.
508, loop detected error
Сервер определяет бесконечный цикл (цикл запросов API). Проблема вызвана слишком большим количеством перенаправлений в цепочке, которая препятствует отображению запрошенных ресурсов или URL-адреса. Для устранения ошибки попытайтесь определить, какие вызовы API вызывают цикл, а затем обратитесь к своему поставщику API за дополнительной помощью.
Об API поверх HTTP
Описывающие HTTP стандарты дают разработчикам достаточно свободы для проектирования API поверх протокола и налагают мало требований на этот API. Например, к МТС Exolve подключилось компания, которая организовала внутрикорпоративную техническую поддержку.
Весь процесс работы автоматизировали, поскольку надо блокировать уволившихся работников, получать выписку по звонкам и настраивать переадресацию с учетом загрузки сотрудников.
Для работы использовались Numbering API и Voice API, которые спроектированы поверх HTTP. Любая компания может работать с МТС Exolve подобным образом, реализовав поддержку этого API у себя.
Другие примеры API, реализованных поверх HTTP:
-
API от Google Docs
-
API от Trello
Заключение
Ошибки API могут быть вызваны множеством факторов, и важно понимать способы их выявления для устранения неполадок. Независимо от того, что у вас случилось, проверьте интернет-соединение, прежде чем пытаться устранить их.
Регулярно отслеживайте производительность API, чтобы заблаговременно обнаруживать проблемы и уменьшать их негативное влияние на ваших пользователей.
Если ошибки API обрабатываются должным образом, их можно быстро устранить с минимальными последствиями для клиентов.