🔌 API: основы
Что такое API, виды, авторизация, форматы данных и как читать документацию.
Теория · Аналитика · #api #http #integration
Определение
API (Application Programming Interface) это договорённость о том, как одна программа обращается к другой. Клиент отправляет запрос, сервер возвращает ответ в известном формате.
Виды API
| Вид | Особенности |
|---|---|
| REST | ресурсы и HTTP-методы, JSON |
| SOAP | XML, строгий контракт WSDL |
| GraphQL | клиент запрашивает нужные поля одним запросом |
| gRPC | бинарный (Protocol Buffers), быстрый, стриминг |
| WebSocket | двусторонний постоянный канал |
| Webhook | сервер сам вызывает ваш адрес по событию |
| Очереди (Kafka, RabbitMQ) | асинхронный обмен сообщениями |
| Библиотечный (SDK) | вызовы внутри кода |
Из чего состоит запрос
URL (адрес и параметры), метод, заголовки (Authorization, Content-Type, Accept), тело.
Авторизация
| Способ | Суть |
|---|---|
| API-ключ | секрет в заголовке или параметре |
| Basic | логин и пароль в Base64 (только по HTTPS) |
| Bearer / JWT | токен в заголовке Authorization: Bearer … |
| OAuth 2.0 | делегированный доступ, токены с правами (scopes) |
| mTLS | клиентский сертификат |
Форматы данных
JSON (по умолчанию), XML, Protocol Buffers, CSV, multipart/form-data для файлов, application/x-www-form-urlencoded.
Как читать документацию
- Базовый адрес и версия.
- Авторизация и получение ключа.
- Список методов: путь, параметры, обязательные поля.
- Примеры запросов и ответов.
- Коды ошибок и лимиты.
- Песочница или Postman-коллекция.
Что проверять при интеграции
Таймауты и повторы, лимиты частоты, идемпотентность, версионность, формат дат (ISO 8601, UTC), кодировки, обработка пустых и необязательных полей, логирование запросов (без секретов).
Быстрый вызов
curl -X GET "https://api.example.com/v1/users?limit=10" \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"