Как читать и понимать документацию API

Если, получив совет “почитать документацию API”, вы так и сделали, но так толком и не поняли, что в ней к чему, то эта статья для вас.

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

Чем лучше документация [API], тем выше скорость внедрения продукта и меньше вопросов к технической поддержке.

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

Не вся документация API создается одинаково

Не все документации API одинаково хороши. Так что же делает документацию API качественной? 

Читаемость.

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

Несмотря на то, что от сайта к сайту она может отличаться, структура у всех документаций будет одинакова:

• аутентификация;
• объект;
• запрос;
• ответ.

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

Stripe

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

Аутентификация

Когда речь идет об аутентификации API, подразумевается безопасность.

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

Если запрос содержит валидный ключ API, то Stripe продолжит его обработку. В противном случае система автоматически вернет ответ с ошибкой 401 — Unauthorized, сообщая запрашивающему о недействительности его учетных данных. Ничего страшного, если вы не знаете, что значит 401, так как мы разберем это в разделе “Ошибки”.

Как и паролями, этой информацией никогда нельзя делиться публично.

Объект

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

Имя и мобильный номер являются атрибутами, описывающими объект клиента. У каждого атрибута есть тип  —  им может быть строка, целое число, дата и т. п. Это обуславливает правила, которые данное значение должно соблюдать. Например, имя наверняка будет иметь строковый тип, в то время как дата рождения будет иметь тип даты. Если вы попробуете создать нового клиента, указав его рождение как “abcdef”, то в ответ наверняка получите ошибку, сообщающую, что в поле дня рождения можно указывать только значение даты.

Рассмотрим реальный объект клиента в Stripe.

Объект клиента в 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 . И все? Да  —  действительно ничего сложного.

Атрибуты данных всегда следуют шаблону ключ:значение.

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

Атрибут клиента в Stripe

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

При изучении объектов данных в документации API нужно обращать внимание на следующее:

• атрибут;
• тип;
• необходимый/необязательный;
• описание.

Заметьте, что в Stripe есть все перечисленные пункты. Возьмем, например, электронную почту. Этот атрибут в объекте клиента является необязательным полем, имеющим строковый тип.

Это означает, что Stripe не требует от вас указания электронной почты при создании объекта клиента. Тем не менее некоторые API такое требование имеют, так что обязательно перепроверяйте документацию API, который используете.

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

Запрос

Когда Оливер Твист просит добавки, он делает запрос. Запросы API действуют аналогично, только имеют более стандартизованную структуру (замените миску и ложку на HTTP-методы, заголовки и полезную нагрузку).

Методы

В контексте объектов данных можно использовать API для выполнения четырех основных функций CRUD:

• Create (создания);
• Read (чтения);
• Update (обновления);
• Delete (удаления).

Например, вы можете создавать клиентов, считывать или извлекать клиента(ов), обновлять их информацию и удалять.

Эти функции CRUD можно перевести в четыре HTTP-метода:

• POST
• GET
• PUT
• DEL

Таблица выше представляет пример Customer API и их связи с CRUD и HTTP-методами. :id  —  это параметр, который можно изменять, указывая на запрашиваемый объект. Вот вы когда-нибудь обращали внимание на URL при посещении веб-страницы?

Его структура аналогична запросу GET /customer/:id. В данном случае :id представлен как songthamtung.

Но имейте ввиду, что такая структура является не абсолютной, а скорее общим образцом. Например, Stripe не следует ей в точности  —  и это нормально, если читатель понимает, как использовать API.

Вообще, в Customer API Stripe даже нет запроса PUT. Вместо него для обновления данных клиентов в нем используется метод POST, который сопровождается :id. Вы могли заметить, что в списке есть дополнительная возможность “List all customers”, которая представляет запрос 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 из командной строки или скрипта оболочки. Аналогично тому, как мы разбирали по частям объект клиента, для понимания происходящего можно разделить и этот запрос.

1. Первая строка  —  это API URL, к которому выполняется запрос curl https://api.stripe.com/v1/customers.
2. Вторая строка служит для аутентификации -u sk_test_4eC39HqLyjWDarjtT1zdp7dc.
3. Последняя строка представляет полезную нагрузку, которую мы отправляем вместе с нашим запросом для создания клиента с описанием -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]"

Полный список возможных атрибутов можете найти в разделе “Data object”. Также отмечу, что в зависимости от API полезная нагрузка может оказаться необязательной.

После совершения запроса всегда можно ожидать получения ответа.

Ответ

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

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

• код статуса;
• полезную нагрузку.

Код статуса

Создатели Stripe старательно заключили HTTP-коды в таблицу выше. Слева в ней приводятся численные трехциферные коды статусов, а справа краткое описание их значений.

В качестве общего правила можно запомнить, что:

• 2XX  —  успех;
• 4XX  —  ошибка клиента;
• 5XX  —  ошибка сервера.

Другими словами, если вы успешно создали клиента с помощью Stripe API, то в качестве кода статуса вернется 200. Если же вы в этом процессе допустили ошибку (например, указав неверные атрибуты), то получите 4XX. Наконец, если вы сделали все верно, но получили 5XX, значит проблема на стороне Stripe.

Так что, когда в следующий раз вы услышите, как разработчики говорят: “Да, я получил 200!” или “Нет, я получил 500!”, то уже будете понимать, о чем идет речь.

Полезная нагрузка ответа

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

Вот, как может выглядеть типичный процесс:

• Если ответ успешный, использовать его полезную нагрузку и выполнить это.
• В противном случае, если ошибка на стороне клиента, использовать полезную нагрузку ответа и выполнить то.
• В остальных случаях вернуть ошибку сервера.

Возьмем, к примеру API клиентов GET /customer/:id:

• Если ответ пришел с кодом успеха 200, вернуть клиента в приложение.
• Если возникла ошибка 404-Not Found, вернуть клиента в приложение с сообщением “Not Found”.
• В остальных случаях вернуть ошибку сервера.

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

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

Если кратко, то код сообщает системе, что делать с возвращенным ответом API.

Если это, тогда  —  то. В противном случае иное.

Заключение

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

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

Читайте также:

• Проектирование базы кода API GraphQL в Node.js
• Генерация API-документации из docstrings на Python
• Автоматический мониторинг скорости API с помощью динамического тестирования

Читайте нас в Telegram, VK

---

Перевод статьи Songtham Tung: How to Read and Understand API Documentation