Что такое API

Введение: Переводчик между программами

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

API (Application Programming Interface) — это такой же “официант” для программ. Это набор правил и протоколов, по которым одна программа может общаться с другой. Вы (ваша программа) отправляете запрос, API его принимает, передает в систему, и возвращает вам ответ.

API определяет:

• Что можно спросить (какие операции доступны)
• Как спросить (формат запроса)
• Что получишь в ответ (формат ответа)

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

Простая аналогия: Ресторан

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

Зачем нужны API

Разделение ответственности

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

Безопасность

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

Масштабирование

API позволяет выстраивать архитектуру, где разные компоненты системы могут быть развернуты на разных серверах, написаны на разных языках и масштабироваться независимо.

Интеграция

API — это клей, соединяющий разные системы. CRM общается с маркетинговой платформой через API. Платежная система общается с интернет-магазином через API.

Экосистема

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

Основные понятия

Клиент (Client)

Программа, которая отправляет запрос к API. Может быть веб-приложением, мобильным приложением, другим сервером, скриптом.

Сервер (Server)

Программа, которая предоставляет API. Принимает запросы, обрабатывает их, возвращает ответы.

Эндпоинт (Endpoint)

Конкретный URL, по которому можно обратиться к API. Например:

• https://api.weather.com/v1/forecast — получить прогноз погоды
• https://api.bank.com/v1/accounts/123/balance — получить баланс счета

Ресурс (Resource)

Объект, с которым работает API. Пользователь, товар, заказ, сообщение — это ресурсы. В REST API каждый ресурс имеет свой эндпоинт.

Запрос (Request)

Сообщение от клиента к серверу. Обычно содержит метод (GET, POST, PUT, DELETE), эндпоинт, заголовки и тело (body).

Ответ (Response)

Сообщение от сервера клиенту. Содержит статус-код (200 OK, 404 Not Found, 500 Internal Server Error), заголовки и тело (обычно JSON или XML).

Метод (HTTP Method)

Действие, которое клиент хочет выполнить:

Статус-коды (HTTP Status Codes)

Типы API по доступу

Публичные API (Public / Open API)

Доступны любому разработчику. Часто бесплатны (с ограничениями) или платны. Примеры: Google Maps API, Twitter API, Telegram API.

Приватные API (Private / Internal API)

Используются внутри компании для общения между своими сервисами. Недоступны извне.

Партнерские API (Partner API)

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

Композитные API (Composite API)

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

Архитектурные стили API

REST (Representational State Transfer)

Самый популярный стиль для веб-API. Основан на HTTP и ресурсах.

Принципы REST:

• Клиент-серверная архитектура
• Отсутствие состояния (stateless) — каждый запрос содержит всю необходимую информацию
• Кеширование
• Единообразие интерфейса
• Слои

Пример REST API:

GET /users/123
Host: api.example.com
Authorization: Bearer token123

{
    "id": 123,
    "name": "Иван",
    "email": "ivan@example.com"
}

GraphQL

Язык запросов, разработанный Facebook. Клиент сам решает, какие поля ему нужны.

Пример GraphQL:

query {
    user(id: 123) {
        name
        email
        orders {
            total
            date
        }
    }
}

Ответ (только то, что попросили):

{
    "data": {
        "user": {
            "name": "Иван",
            "email": "ivan@example.com",
            "orders": [
                {"total": 5000, "date": "2024-01-15"},
                {"total": 3000, "date": "2024-02-20"}
            ]
        }
    }
}

REST vs GraphQL:

SOAP (Simple Object Access Protocol)

Старый, тяжеловесный протокол на основе XML.

Пример SOAP запроса:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <GetUser>
            <UserId>123</UserId>
        </GetUser>
    </soap:Body>
</soap:Envelope>

Когда используется: В корпоративных системах (банки, страховые), где важны строгие контракты и WS-Security.

gRPC (Google Remote Procedure Call)

Современный высокопроизводительный протокол от Google. Использует Protocol Buffers для сериализации.

Особенности:

• Очень быстрый (бинарный протокол)
• Поддержка потоковой передачи (streaming)
• Сильная типизация
• Генерация клиентского кода из .proto файлов

Когда используется: Внутренние микросервисы, высоконагруженные системы.

WebSocket

Протокол для полно-дуплексной связи (двусторонней). Соединение остается открытым, сервер может отправлять данные клиенту без запроса.

Когда используется: Чаты, онлайн-игры, биржевые котировки, совместное редактирование документов.

Примеры API в реальной жизни

Пример 1: Погодное приложение

GET https://api.openweathermap.org/data/2.5/weather?q=Moscow&appid=API_KEY

{
    "weather": [{"main": "Clouds", "description": "пасмурно"}],
    "main": {"temp": 15.5, "feels_like": 14.2, "humidity": 78},
    "wind": {"speed": 3.6}
}

Пример 2: Платежная система (Stripe)

POST https://api.stripe.com/v1/charges
Authorization: Bearer sk_test_xxx
Content-Type: application/x-www-form-urlencoded

amount=1000&currency=usd&source=tok_visa&description=Заказ+№123

{
    "id": "ch_1ABC123",
    "amount": 1000,
    "currency": "usd",
    "status": "succeeded",
    "description": "Заказ №123"
}

Пример 3: Социальная сеть (Twitter)

POST https://api.twitter.com/2/tweets
Authorization: Bearer AAAAAAAAA...
Content-Type: application/json

{
    "text": "Привет, мир!"
}

{
    "data": {
        "id": "1234567890",
        "text": "Привет, мир!"
    }
}

Как проектируются API

Принципы хорошего API

Последовательность:

• Одинаковые имена ресурсов во всех эндпоинтах
• Одинаковые форматы ответов
• Одинаковые статус-коды для одинаковых ситуаций

Простота:

• Интуитивно понятные эндпоинты
• Минимум вложенности
• Предсказуемое поведение

Безопасность:

• Аутентификация (кто ты)
• Авторизация (что тебе можно)
• HTTPS обязательно

Документация:

• Понятное описание каждого эндпоинта
• Примеры запросов и ответов
• Описание ошибок

Версионирование API

API меняется со временем. Нужен способ обновлять API, не ломая существующих клиентов.

Способы версионирования:

# 1. В URL (самый популярный)
GET /v1/users/123
GET /v2/users/123

# 2. В заголовке
GET /users/123
Accept: application/vnd.myapi.v1+json

# 3. В параметре
GET /users/123?version=1

Пагинация

Когда ресурсов много, API не должен возвращать их все сразу.

# Постраничная навигация (offset/limit)
GET /users?limit=10&offset=20

# Курсорная пагинация (ключ)
GET /users?limit=10&after=123

{
    "data": [...],
    "pagination": {
        "next": "/users?limit=10&after=456",
        "prev": "/users?limit=10&before=789"
    }
}

Фильтрация и сортировка

# Фильтрация
GET /users?status=active&city=Москва

# Сортировка
GET /users?sort=-created_at,name

# Поиск
GET /users?search=Иван

Безопасность API

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

API Key: Простой ключ, часто в заголовке или параметре.

GET /data?api_key=abc123
# или
X-API-Key: abc123

Basic Auth: Имя пользователя и пароль (в Base64).

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Bearer Token (JWT): Токен, полученный после логина.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

OAuth 2.0 / OIDC: Позволяет пользователю дать приложению доступ к своим данным без передачи пароля. Используется для входа через Google, Facebook, GitHub.

Ограничения (Rate Limiting)

Чтобы один клиент не перегрузил сервер.

# Ответ может содержать заголовки с лимитами
X-RateLimit-Limit: 1000      # максимум запросов в час
X-RateLimit-Remaining: 987   # осталось
X-RateLimit-Reset: 1704067200 # когда сброс (timestamp)

# При превышении — статус 429 Too Many Requests

CORS (Cross-Origin Resource Sharing)

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

Access-Control-Allow-Origin: https://myapp.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE

Документация API

OpenAPI (Swagger)

Стандарт описания REST API. Позволяет генерировать документацию, клиентский код, серверные заглушки.

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Получить пользователя
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Успех
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string

Другие форматы

• RAML (RESTful API Modeling Language)
• API Blueprint
• Postman Collections (для тестирования)

Инструменты для работы с API

cURL

Консольная утилита для отправки HTTP запросов.

# GET запрос
curl https://api.example.com/users/123

# POST запрос с JSON
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Иван", "email": "ivan@example.com"}'

# С заголовком авторизации
curl https://api.example.com/data \
  -H "Authorization: Bearer token123"

Postman

Графический инструмент для тестирования API. Позволяет:

• Отправлять запросы разных типов
• Сохранять коллекции запросов
• Автоматизировать тесты
• Генерировать документацию

Insomnia, Bruno

Альтернативы Postman.

Практические примеры: REST API

Создание пользователя (POST)

POST /api/users
Content-Type: application/json
Authorization: Bearer admin_token

{
    "name": "Иван Петров",
    "email": "ivan@example.com",
    "role": "user"
}

Успешный ответ (201 Created):

{
    "id": 123,
    "name": "Иван Петров",
    "email": "ivan@example.com",
    "role": "user",
    "created_at": "2024-01-15T10:30:00Z"
}

Ошибка (400 Bad Request):

{
    "error": "email already exists",
    "code": "DUPLICATE_EMAIL"
}

Получение пользователя (GET)

GET /api/users/123
Authorization: Bearer user_token

Успешный ответ (200 OK):

{
    "id": 123,
    "name": "Иван Петров",
    "email": "ivan@example.com",
    "role": "user",
    "created_at": "2024-01-15T10:30:00Z"
}

Не найдено (404 Not Found):

{
    "error": "user not found",
    "code": "NOT_FOUND"
}

Обновление пользователя (PUT / PATCH)

PATCH /api/users/123
Content-Type: application/json
Authorization: Bearer user_token

{
    "phone": "+7-999-123-45-67"
}

Удаление пользователя (DELETE)

DELETE /api/users/123
Authorization: Bearer admin_token

Успешный ответ (204 No Content) — без тела.

Распространенные ошибки

Ошибка 1: Слишком много данных в одном ответе

API возвращает 10 000 пользователей за раз, когда клиенту нужны только первые 10.

Как исправить: Пагинация.

Ошибка 2: Неправильные статус-коды

Возвращать 200 OK с {"error": "not found"} вместо 404.

Как исправить: Использовать правильные HTTP статус-коды.

Ошибка 3: Отсутствие версионирования

Изменили API, и все старые клиенты сломались.

Как исправить: Версионирование с самого начала.

Ошибка 4: Слишком много запросов (N+1 проблема)

Клиент делает один запрос к списку, а потом по одному запросу для каждого элемента.

Как исправить: Проектировать API, возвращающее связанные данные вместе (например, orders с items внутри).

Ошибка 5: Непонятные сообщения об ошибках

{"error": "something went wrong"} — бесполезно.

Как исправить: Понятные сообщения, код ошибки, возможно, ссылка на документацию.

{
    "error": "invalid parameter 'email'",
    "code": "INVALID_PARAMETER",
    "details": "email must be a valid email address",
    "documentation": "https://api.example.com/docs/errors#INVALID_PARAMETER"
}

Резюме для системного аналитика

1. API (Application Programming Interface) — контракт между программами. Определяет, как одна программа может общаться с другой, скрывая внутреннюю сложность.

2. Аналогия с рестораном: Вы (клиент) → Меню (документация) → Официант (API) → Кухня (сервер). Официант скрывает всю сложность приготовления.

3. Основные компоненты: эндпоинт (URL), метод (GET, POST, PUT, DELETE), заголовки, тело запроса/ответа, статус-код.

4. REST — самый популярный стиль. Основан на ресурсах и HTTP методах. Stateless (без состояния), кешируемый, единообразный.

5. GraphQL дает клиенту контроль над тем, какие поля получать. REST проще в кешировании, GraphQL — в сложных запросах.

6. Безопасность: аутентификация (API Key, JWT, OAuth), авторизация (проверка прав), HTTPS, rate limiting.

7. Документация (OpenAPI) критически важна. Без нее API невозможно использовать. Хорошая документация — это половина успеха API.

8. Версионирование позволяет эволюционировать API без поломки существующих клиентов. Лучше заложить с первого дня.