6 часто возникающих ошибок API и как их предотвратить

API становятся все более важной частью экономики XXI века и нашей повседневной жизни. Огромные компании, такие как Stripe и Amazon, были построены на отличных платформах для разработчиков. Даже «аналоговые» инструменты, такие как офисные телефонные системы, становятся доступными API. Все более совершенные продукты VoIP интегрируются телефонные системы для малого бизнеса с таким программным обеспечением, как Google Workspace. Это открывает новые возможности для сотрудников и клиентов. Но API не исключают ошибок. Являетесь ли вы разработчиком проектов-любителей или обладателем миллиона долларов SaaS-продукт пользователь, вы обнаружите, что сбои неизбежны.

Что такое ошибка/сбой API?

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

6 распространенных ошибок API

Некоторые распространенные ошибки API:

• Ошибки HTTP/HTTPS.
• Бесполезные ошибки API.
• Смешение методов.
• Отсутствуют заголовки Content-Type/Accept.
• Ошибки авторизации.
• Ошибки форматирования данных.

1. Ошибки HTTP/HTTPS

Одна из наиболее распространенных ошибок API возникает, когда в URL-адресах путаются протоколы http:// и https://.

Для разработчиков проблема в том, что некоторые API поддерживают только протокол HTTP, а другие совместимы с HTTPS. Некоторые поддерживают разные стандарты на разных конечных точках в одном и том же клиентоориентированном продукте.

Это может стать еще более запутанным, когда разработчики объединяют несколько API. Если они являются штатными разработчиками, создающими решения «сделай сам» для асинхронного бизнес-коммуникации с удаленными командами. Разработчикам приходится тратить время на поиск конечной точки, вызывающей проблему, а затем создавать обходной путь, позволяющий двум остальным API взаимодействовать друг с другом.

Если вы API провайдер, вы можете предотвратить эту ошибку, применив определенные стратегии HTTPS. Например, ваш API может автоматически перенаправлять HTTP-запросы на HTTPS-запросы по мере их поступления.

2. Бесполезные сообщения об ошибках API

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

HTTP предоставляет более 70 кодов состояния HTTP, но вам нужно реализовать как минимум наиболее распространенные из них, с которыми привыкли работать разработчики. Примеры таких включают:

200 ОК

Все хорошо! Будьте осторожны и указывайте этот код состояния только в том случае, если все на самом деле is ХОРОШО. Известно, что API-интерфейс Facebook Graph предоставляет код 200 всякий раз, когда он успешно возвращает какой-либо вывод, даже если этот вывод содержит код ошибки.

400 Bad Request

Почти всегда это происходит из-за опечатки во вводе пользователя. Но это не значит, что вы сошли с крючка! Убедитесь, что в сообщении об ошибке указаны некоторые подробности ошибочного ввода, чтобы пользователь мог быстро его исправить.

401 Несанкционированный

Этот статус означает, что ввод в порядке, но в запросе пользователя отсутствует код авторизации. Не путать с…

403 Запрещено

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

404 не найдено

Запрос пользователя действителен, но конечная точка или ресурс, который он запрашивает, не существует. Возможно, это связано с тем, что файл уже был удален, но убедитесь, что это не вызвано ошибкой HTTP/HTTPS.

429 слишком много запросов

Это происходит, когда один и тот же пользователь пытается вызвать API слишком много раз подряд. После ряда громких DDoS-атак за последнее десятилетие веб-сервисы внимательно следят за тем, кто и как часто обращается к их серверу.

Это ограничение скорости аналогично тому, что можно найти в любом домене или на других крупных сайтах. Поставщики веб-хостинга, такие как Cloudflare, обеспечивают защиту от DDoS для доменов, размещенных на их серверах. Для API эти средства защиты должны быть встроены.

Ошибки API 5xx

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

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

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

Взгляните на это сообщение об ошибке от Twilio, чей API позволяет разработчикам совершать вызовы VoIP.

«`

{

«код»: 21211,

«message»: «Номер «Кому» 5551234567 не является действительным номером телефона.»,

«more_info»: «https://www.twilio.com/docs/errors/21211»,

«Статус»: 400

}

«`

Помимо стандартного статуса 400, вверху есть собственный код ошибки «21211». В сообщении даже упоминается конкретный виртуальный номер телефона, который вызывает проблему. Он отсылает пользователя на страницу документации, где обсуждается проблема 21211.

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

3. Смешение методов

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

Другая причина ошибок метода — неясная документация. Это может произойти, если в разделе вашей документации не объясняется, какие методы требуются, или если используется неправильный глагол. (Остерегайтесь использования слов «get» и GET как взаимозаменяемых слов. Убедитесь, что форматирование ваших документов четкое, и сохраните себе электронное письмо в службу поддержки клиентов.)

4. Отсутствуют заголовки Content-Type/Accept.

Большинство вызовов API имеют как минимум две части данных заголовка: Content-Type и Accept. Эти заголовки помогают двум сторонам (например, двум API) согласовать, какой тип данных отправляется и какие типы будут приняты взамен. Как и любые переговоры, они могут сорваться.

Некоторые API будут принимать запросы, не имеющие этих заголовков, если нет причин быть настолько строгими. Каждая строка кода вносит возможные ошибки в программное обеспечение, поэтому поставщики облачных УАТС часто не указывают требования к заголовку, если в этом нет необходимости. Но в коммерческих API, связанных с безопасностью, разработчики будут запрашивать определенные заголовки Content-Type и Accept. Это позволяет им жестко контролировать, что разрешено входить в их систему и что разрешено проходить.

Content-Type сообщает API формат даты, которую вы отправляете, а Accept сообщает API, что отправлять обратно. Для API может потребоваться только наличие удалось в заголовках некоторые принимают определенные типы и отклоняют другие.

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

5. Ошибки авторизации

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

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

Убедитесь, что запросы API OAuth 2 отформатированы следующим образом: перед закрытым ключом стоит флаг «Носитель»:

«`

Авторизация: носитель {your_api_key_here}

«`

Пары имени пользователя и пароля должны иметь формат «имя пользователя:пароль». Но даже если запрос API не требует пароля, пользователям, возможно, придется добавить двоеточие в конце. Поставщики API могут сами добавить двоеточие или указать в документации, что такое форматирование.

6. Ошибки форматирования данных

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

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

Мы упомянули методы запроса, которые по умолчанию используют GET из-за перенаправления. Но чаще всего эта ошибка возникает, когда пользователь не указал заголовок Accept правильно, если вообще указал его. Это может дать провайдерам повод быть более строгими в отношении того, какие типы контента они принимают, даже если это не представляет угрозы безопасности.

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

Объяснение предотвращения ошибок

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

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