REST API

Что такое API

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

Примеры API из жизни

GET /api/weather?city=Moscow HTTP/1.1

← Ответ:
{
  "city": "Moscow",
  "temp": 22,
  "condition": "sunny"
}

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

API бывают разные

Что такое REST

REST (Representational State Transfer) — архитектурный стиль для построения веб-сервисов. Не протокол, не стандарт, не библиотека — именно стиль. Набор принципов которые описывают как должно быть организовано взаимодействие между клиентом и сервером.

REST описал Рой Филдинг в 2000 году в докторской диссертации. Филдинг — один из авторов спецификации HTTP/1.1. Он не придумывал новый протокол — взял HTTP и сформулировал правила при соблюдении которых система получается масштабируемой, простой и надёжной.

Ключевая идея: всё есть ресурс. Пользователь — ресурс. Заказ — ресурс. Статья — ресурс. У каждого ресурса есть уникальный адрес (URL) и с ним можно выполнять стандартные операции через HTTP-методы.

Не нужно придумывать специальные команды вроде getUserById или removeUser — стандартные HTTP-методы уже описывают действие. URL указывает с чем, метод указывает что делать.

Шесть принципов REST

Филдинг сформулировал шесть ограничений. Система которая соблюдает их — RESTful. На практике мало кто соблюдает все шесть буквально, но понимать их нужно — они объясняют почему REST-системы спроектированы именно так.

Ответственность слоёв

Принцип Layered System — не просто теория. В реальной инфраструктуре он определяет кто за что отвечает. Каждый слой делает своё дело и не лезет в чужое.

Почему это важно:

• Независимость обновлений. Обновление nginx не требует перезапуска бэкенда. Замена алгоритма балансировки в HAProxy не трогает ни nginx, ни бэкенд.
• Чёткие зоны ответственности. Запросы распределяются неравномерно — проблема HAProxy. Сертификат не обновился — проблема nginx. API возвращает неправильные данные — проблема бэкенда.
• Масштабирование по слоям. Нагрузка выросла — добавляешь бэкенд-серверы, HAProxy распределит на них трафик. nginx и бэкенды не знают друг о друге напрямую.

REST на практике: как читать эндпоинты

В повседневной работе ты сталкиваешься с конкретными URL-ами в конфигах nginx и логах. Нужно уметь читать их и понимать структуру.

Структура URL в REST API

• Коллекция — существительное во множественном числе: /users, /orders, /products
• Конкретный ресурс — коллекция + идентификатор: /users/42
• Вложенные ресурсы — иерархия принадлежности: /users/42/orders — заказы конкретного пользователя
• Версионирование — /v1/, /v2/ — позволяет менять API не ломая старых клиентов
• Query-параметры — фильтрация, сортировка, пагинация: ?status=active&page=2&limit=20

Метод + URL = действие

Как это выглядит в nginx

location /api/v1/ {
    proxy_pass http://backend-v1;    # бэкенд версии 1
}
location /api/v2/ {
    proxy_pass http://backend-v2;    # бэкенд версии 2
}
location /static/ {
    root /var/www;                   # статика с диска
}

Как читать логи

Понимая REST, ты сразу читаешь что происходит — без документации. Без понимания структуры это просто набор символов.

Итог

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

Всё что мы изучили в главах 1–4 — методы, заголовки, коды ответов, TLS, проксирование — это инструменты на которых REST построен. REST не добавляет ничего нового к HTTP — он описывает как использовать HTTP правильно.