Объясняется на примере Stripe API
Если кто-то сказал вам «проверить документацию по API», и вы это сделали, но не уверены, на что смотрите, это для вас.
API есть везде. Они соединяют разные приложения вместе и являются основой большинства интеграций. Другими словами, API — это общий язык, который используется для связи между различными системами.
Чем лучше документация [API], тем выше скорость внедрения и меньше вопросов к техподдержке.
Не волнуйтесь, вам не нужно иметь техническое образование, чтобы продолжить. Основная идея заключается в том, что происходит обмен запросами и ответами. Но как мы можем знать, о чем спрашивать и каких результатов ожидать? Ответ заключается в понимании документации API.
Не вся документация по API одинакова
Не вся документация по API одинакова. Некоторые из них превосходны, а другие… не очень (они вообще существуют?). Так что же отличает документацию API от плохо написанной?
Читаемость.
Лучшая документация по API — это справочник по самообслуживанию, в котором кратко объясняется, что возможно, а что нет, и с чего начать. Он также служит местом, где пользователи могут вернуться с вопросами о синтаксисе или функциональности. Так почему это важно? Ну а чем качественнее документация, тем выше скорость внедрения и меньше вопросов к техподдержке.
Хотя документация API может варьироваться от сайта к сайту, все они имеют одну и ту же структуру, состоящую из:
- Аутентификация
- Объект
- Запрос
- Ответ
В следующих разделах мы рассмотрим каждый пункт и обобщим их, используя в качестве примера документ Stripe API.
Полоса
Для тех из вас, кто может быть не знаком с Stripe, это одно из крупнейших программ для обработки онлайн-платежей для интернет-бизнеса, и у них есть одна из лучших доступных документов API.
Это ссылка на их документацию по API https://stripe.com/docs/api.
Отказ от ответственности. Я никоим образом не связан с Stripe. Причина, по которой я выбрал документацию Stripe API, заключается в ее первоклассной удобочитаемости. Он отличается элегантным двухпанельным дизайном с пояснениями, написанными на простом английском языке слева, и фрагментами кода справа. Также есть удобная боковая панель, позволяющая быстро перемещаться по доступным ресурсам. Как и следовало ожидать, в нем есть вся необходимая информация, необходимая для того, чтобы сразу приступить к работе.
Аутентификация
Когда вы думаете об аутентификации API, вы должны думать о безопасности 🔒.
Stripe необходимо знать, кто делает запросы и уполномочены ли они на это. Для этого для каждого запроса, который мы делаем, нам нужно отправить его с API KEY,или секретным кодом, который обычно генерируется с использованием информации, относящейся к учетной записи, такой как имя пользователя и пароль.
Если запрос содержит действительный ключ API, Stripe продолжит обработку запроса. В противном случае Stripe автоматически вернет ответ об ошибке 401 — Unauthorized, чтобы сообщить запрашивающему, что его учетные данные недействительны. Ничего страшного, если вы не знаете, что означает 401, мы расскажем об этом в разделе «Ошибки».
Как и в случае с паролем, мы никогда не должны разглашать эту информацию публично.
Объект
Объекты представляют информацию. С технической точки зрения, вы можете думать об объектах как о записях в таблицах базы данных. Например, предположим, что у нас есть данные о клиенте, такие как имя и мобильный телефон. Скорее всего, это будет храниться в базе данных внутри таблицы клиентов, с которой мы можем взаимодействовать через API, поддерживающие объекты клиентов, такие как создание нового клиента или извлечение существующего.
Имя клиента и мобильный телефон — это атрибуты данных, которые описывают объект клиента. Каждый атрибут данных имеет тип — будь то строка, целое число, дата и т. д. значение должно соблюдаться. Например, имя, скорее всего, будет строковым типом, а день рождения, скорее всего, будет типом даты. Если вы попытались создать нового клиента с днем рождения как «abcdef», то это, скорее всего, вернет ошибку, в которой говорится, что вы можете сохранить только значение даты в поле дня рождения.
Давайте взглянем на реальный объект клиента в Stripe.
Полосатый объект клиента
Stripe проделал большую работу, чтобы сделать объект клиента легко читаемым. Правая сторона представляет пример объекта клиента в формате JSON, тогда как левая сторона определяет атрибуты данных.
Не паникуйте, если этот формат выглядит «слишком техническим». Я объясню, как читать это на простом английском языке, начиная с правой стороны.
{
"id": "cus_L3OFQQ0ihEvq03",
"object": "customer",
"address": null,
"balance": 0,
"created": 1643464809,
"currency": "usd",
"default_source": null,
"delinquent": false,
"description": null,
"discount": null,
"email": null,
"invoice_prefix": "B22171F",
"invoice_settings": {
"custom_fields": null,
"default_payment_method": null,
"footer": null
},
"livemode": false,
"metadata": {},
"name": null,
"next_invoice_sequence": 1,
"phone": null,
"preferred_locales": [],
"shipping": null,
"tax_exempt": "none"
}Объект данных выше представляет одного клиента.
Если начать сверху "id": "cus_L3OFQQ0ihEvq03", это означает, что id этого клиента равно cus_L3OFQQ0ihEvq03 . Вот и все? Да — это действительно так просто.
Атрибуты данных всегда соответствуют шаблону key:value.
Если вы работаете с электронными таблицами, вы можете представить ключ как заголовок столбца, а значение как значение строки ячейки. На самом деле они взаимозаменяемы, что означает, что вы можете легко конвертировать между табличным форматом и форматом JSON. Это еще один способ для людей (и машин) читать, понимать и работать с объектами данных.
Полоса атрибута клиента
Атрибуты данных важны. Они помогают разработчикам понять, какие поля можно использовать для объекта данных.
При ссылке на объекты данных в документах API следует обращать внимание на следующее:
- Атрибут
- Тип
- Обязательный/необязательный
- Описание
Обратите внимание, что в Stripe есть все вышеперечисленное. Например, мы можем взять электронную почту. Атрибут электронной почты в объекте клиента Stripe является необязательным полем строкового типа.
Это означает, что Stripe не требует от вас значения электронной почты при создании объекта клиента. Однако некоторые API делают это, поэтому обязательно перепроверьте документацию API, которую вы используете.
Описание также важно и может предоставить ключевую информацию, которую мы могли бы пропустить в противном случае. В этом случае мы знаем, что электронная почта имеет ограничение в 512 символов.
Запрос
Когда Оливер Твист просит еще, он просит. Запросы API ведут себя аналогичным образом, хотя и имеют более стандартную структуру (замените миску и ложку HTTP-методами, заголовками и полезной нагрузкой).
Методы
В контексте объектов данных вы можете использовать API для выполнения четырех основных функций CRUD:
- Создавать
- Читать
- Обновлять
- Удалить
Например, вы можете создавать клиентов, читать или извлекать клиентов, обновлять информацию о клиентах и удалять их.
Эти функции CRUD можно преобразовать в четыре метода HTTP:
- ПОЧТА
- ПОЛУЧАТЬ
- ПОМЕЩАТЬ
- ДЕЛ
В приведенной выше таблице приведен пример клиентских API и их связи с методами CRUD и HTTP. :id — это параметр, который вы можете изменить, чтобы указать объект, который вы запрашиваете. Например, вы когда-нибудь замечали URL-адрес при посещении веб-страницы, такой как LinkedIn?
Это похоже на запрос GET /customer/:id. :id в данном случае — это songthamtung.
Важно отметить, что эта структура не является абсолютной, а скорее является общим ориентиром для подражания. Stripe, например, не следует этому до буквы T — и это нормально, если читатель понимает, как использовать API.
Клиентский API Stripe на самом деле даже не содержит запроса PUT. Вместо этого для обновления клиентов они используют метод POST и передают :id . Вы могли заметить, что есть дополнительная функция «Список всех клиентов», которая представляет собой запрос GET, который не принимает никаких :id.
Существуют различные способы вызова конечной точки API. Объедините это с полезной нагрузкой запроса, и у вас будет еще больше возможностей.
Запрос полезной нагрузки
Полезная нагрузка или тело запроса — это данные, отправленные с запросом API. Здесь вы можете указать информацию, которую вы хотите передать системе, которую вы вызываете.
Например, когда вы хотите создать клиента, вы должны передать определенные данные, такие как имя и адрес электронной почты. Эти данные содержатся в полезной нагрузке запроса.
curl https://api.stripe.com/v1/customers \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d description="My First Test Customer (created for API docs)"
Это запрос cURL, который позволяет вам выполнять вызовы API из командной строки или сценария оболочки. Подобно тому, как мы разбили объект клиента, мы можем проанализировать его, чтобы понять, что происходит.
- Первая строка — это URL-адрес API, к которому мы отправляем запрос
curl https://api.stripe.com/v1/customers. - Вторая строка предназначена для authentication
-u sk_test_4eC39HqLyjWDarjtT1zdp7dc. - Последняя строка — это полезная нагрузка, которую мы отправляем вместе с нашим запросом на создание клиента с описанием
-d description=”My First Test Customer (created for API docs)”.
Мы можем легко добавить имя и адрес электронной почты в полезную нагрузку запроса, используя следующий синтаксис.
curl https://api.stripe.com/v1/customers \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d description="My First Test Customer (created for API docs)" \ -d name="Songtham Tung" \ -d email="[email protected]"
Полный список возможных атрибутов, которые мы можем использовать, см. в разделе определения объекта данных. Я также хотел бы упомянуть, что в зависимости от API полезная нагрузка запроса может не понадобиться.
После того, как вы сделаете запрос, вы всегда можете рассчитывать на получение ответа.
Ответ
Ньютон не говорил, что на каждый запрос API есть равный и противоположный ответ API. Тем не менее, здесь можно применить те же принципы, что и в третьем законе движения.
Был ли это успех или неудача, вы всегда получите ответ, который содержит
- Код состояния
- Полезная нагрузка
Код состояния
Stripe отлично справилась с инкапсуляцией кодов состояния HTTP в таблице выше. С левой стороны находятся трехзначные коды состояния, а с правой стороны краткое описание того, что это означает.
Эмпирическое правило заключается в том, что
- 2ХХ — успех
- 4XX — ошибка клиента
- 5ХХ — ошибка сервера
Другими словами, если вы успешно создали клиента с помощью Stripe API, то возвращенный код состояния будет 200. В противном случае, если вы допустили ошибку (будь то несанкционированный доступ, неправильные атрибуты и т. д.), вы получите 4XX. И, наконец, если вы все сделали правильно, но получили 5XX, то проблема с Stripe.
Так что в следующий раз, когда вы услышите, как разработчики говорят: «Да, я получил 200!» или «Нет, у меня 500!», вы поймете, о чем они говорят.
Полезная нагрузка ответа
В дополнение к коду состояния ответы API также включают полезную нагрузку. Подобно полезной нагрузке запроса, полезная нагрузка ответа — это просто возвращаемые данные. Возвращаемые данные содержат важную информацию, которую разработчики могут использовать для корректной обработки как успешных, так и неудачных ответов.
Вот типичный пример того, как это может выглядеть
- Если ответ успешен, используйте полезную нагрузку ответа и сделайте это
- В противном случае, если произошел сбой из-за ошибки клиента, используйте полезную нагрузку ответа и сделайте это.
- Иначе вернуть ошибку сервера
Если мы возьмем, например, API клиентов GET /customer/:id
- Если ответ будет успешным
200, вернуть клиента в приложение - В противном случае, если произошел сбой из-за
404 — Not Found, вернуть клиента, не найденного в приложение. - Иначе вернуть ошибку сервера
Обработка ошибок (и успехов) настолько важна, что в Stripe даже есть специальный раздел для этого, полный примеров кода из поддерживаемых библиотек.
Мы не будем вдаваться в подробности здесь, так как я не ожидаю, что вы знаете, как читать и понимать язык программирования. Однако я хотел поднять этот вопрос, чтобы показать вам, как может выглядеть обработка ответов API в реальном сценарии.
Короче говоря, код сообщает системе, что делать с возвращаемым ответом API.
Если это, то это. В противном случае сделайте что-нибудь еще.
Заключение
Поздравляю, если вы зашли так далеко! Это непростая вещь. Поначалу чтение документации по API может показаться трудным, но существует базовый шаблон или язык как таковой, который делает это повсеместной формой общения.
Не вся документация по API создается одинаково, но большинство API, как правило, группируются в ресурсы, такие как Customers. Оттуда вы можете взглянуть на пример запроса и ответа, а также на соответствующие атрибуты и примеры объектов данных в полезной нагрузке.
Что вы с этим сделаете… ну, полностью зависит от вас и вашей команды. Более подробное руководство по реализации API можно найти в другой статье, в которой мы исследуем, как можно использовать диаграммы последовательности для визуализации оркестровки API здесь.
Приятного чтения!
