Урок 2. Как читать API-документацию

Урок 2. Как читать API-документацию#

Цель: научиться находить нужную информацию в API-документации без технических знаний.

Что есть в API-документации#

Любая хорошая API-документация содержит:

1. Введение (Getting Started) — как начать работу, как получить доступ
2. Авторизация (Authentication) — как подтвердить, что вы имеете право использовать API
3. Эндпоинты (Endpoints) — список доступных действий (читать клиентов, создать заказ, отправить email)
4. Параметры (Parameters) — какие данные нужно передать в запросе
5. Ответы (Responses) — какие данные вернёт API (успех / ошибка)
6. Примеры (Examples) — готовые примеры запросов
7. Лимиты (Rate Limits) — сколько запросов можно сделать в минуту / час / день
8. Стоимость (Pricing) — сколько стоит использование API

Как найти нужное действие (эндпоинт)#

Шаг 1. Определить, что вы хотите сделать

Например: «Я хочу прочитать список клиентов из CRM».

Шаг 2. Найти раздел с нужным ресурсом

В документации ищите раздел «Clients» или «Customers» или «Contacts».

Шаг 3. Найти нужное действие

Действия обычно называются так:

• GET /clients — прочитать список клиентов
• GET /clients/{id} — прочитать одного клиента по ID
• POST /clients — создать нового клиента
• PUT /clients/{id} — обновить клиента
• DELETE /clients/{id} — удалить клиента

Шаг 4. Прочитать, какие параметры нужны

Например, для POST /clients (создать клиента) могут потребоваться:

• name (обязательно) — имя клиента
• email (обязательно) — email клиента
• phone (необязательно) — телефон

Шаг 5. Посмотреть пример запроса

В хорошей документации всегда есть примеры. Скопируйте пример и адаптируйте под свои данные.

Пример: документация Stripe API#

Задача: создать платёжный линк для клиента.

Шаг 1. Открыть документацию Stripe

Перейдите на stripe.com/docs/api

Шаг 2. Найти раздел «Payment Links»

В боковом меню → Payment Links → Create a payment link

Шаг 3. Прочитать описание

Creates a payment link.

Шаг 4. Посмотреть параметры

• line_items (обязательно) — список товаров
  • price — ID цены (создаётся заранее)
  • quantity — количество
• after_completion (необязательно) — что делать после оплаты

Шаг 5. Посмотреть пример

POST https://api.stripe.com/v1/payment_links
{
  "line_items": [
    {
      "price": "price_1A2B3C4D5E6F",
      "quantity": 1
    }
  ]
}

Шаг 6. Прочитать, какой будет ответ

{
  "id": "plink_1A2B3C4D5E6F",
  "url": "https://checkout.stripe.com/pay/cs_test_abc123",
  "active": true
}

Вы получите url — это ссылка для оплаты, которую можно отправить клиенту.

Чек-лист «Как читать документацию»#

• Открыть раздел «Getting Started» или «Introduction» — понять общую логику
• Найти раздел авторизации — понять, как получить ключ доступа
• Найти нужный ресурс (Clients, Orders, Payments) — понять, какие действия доступны
• Прочитать описание эндпоинта — понять, что он делает
• Посмотреть параметры — понять, какие данные нужно передать
• Посмотреть пример запроса — скопировать и адаптировать
• Посмотреть пример ответа — понять, что вы получите обратно
• Прочитать раздел «Rate Limits» — понять, сколько запросов можно делать
• Прочитать раздел «Pricing» — понять, сколько это стоит