API и REST: как программы разговаривают друг с другом

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

Программы тоже разговаривают

До сих пор «клиентом» сервера был браузер, а читал ответ человек. Но в вебе всё чаще разговаривают друг с другом программы: ваша страница просит у сервера список предложений (вы делали это в уроке про fetch), мобильное приложение отправляет заявку, сайт магазина спрашивает у службы доставки цену, а нейросеть читает данные через инструмент. Для таких разговоров нужны правила: что спрашивать, в каком виде, какие ответы бывают. Набор таких правил называют API (Application Programming Interface, программный интерфейс приложения).

Чаще всего веб-API это обычный HTTP, уже знакомый вам: запрос с методом и адресом, ответ с кодом и телом, и тело обычно в JSON. Отличие от страницы только в том, что ответ рассчитан не на глаза, а на программу.

REST: ресурсы и глаголы

Самый распространённый стиль таких API называется REST (Representational State Transfer). В 2000 году его описал в докторской диссертации Рой Филдинг, один из авторов HTTP. Идея в том, чтобы использовать HTTP так, как он задуман:

• в адресе называют ресурс, то есть существительное во множественном числе: /items (предложения), /items/7 (седьмое предложение), /requests (заявки);
• действие выражает метод HTTP, а не слово в адресе;
• результат сообщает код состояния;
• сервер не хранит между запросами ничего о клиенте: всё нужное приходит в самом запросе.

Честности ради: то, что в индустрии называют «REST API», обычно лишь следует этой идее приблизительно (строгий REST требует ещё ссылок в ответах, и их почти никто не делает). Для нас важны сами правила, они делают API предсказуемым: увидев /items, любой разработчик догадается, как выглядит /requests.

Методы

Каждый метод имеет принятый смысл, записанный в стандарте HTTP (RFC 9110):

• GET: прочитать. Он безопасен: ничего не меняет, поэтому его можно вызывать сколько угодно раз и кому угодно (браузеру, поисковому роботу, расширению).
• POST: создать новый ресурс или выполнить действие («отправить заявку»). Повтор может создать вторую копию, поэтому POST не идемпотентен.
• PUT: заменить ресурс целиком.
• PATCH: изменить часть полей.
• DELETE: удалить.

Слово идемпотентный значит «повтор не меняет результат»: два одинаковых DELETE /items/7 оставят сервер в том же состоянии, что и один. GET, PUT и DELETE идемпотентны, и клиент может смело повторить запрос, если ответа не было. POST этого не гарантирует, поэтому в уроке про fetch мы блокировали кнопку на время отправки.

Коды ответа

Вы знаете группы кодов (2xx, 3xx, 4xx, 5xx). В API используют вполне определённый набор:

• 200 OK: успех; 201 Created: создано (с заголовком Location: адрес нового ресурса); 202 Accepted: принято, обработка позже; 204 No Content: успех без тела;
• 400 Bad Request: запрос неверен (пропущено поле); 401 Unauthorized: нужно войти; 403 Forbidden: войти недостаточно, нельзя; 404 Not Found: такого ресурса нет; 409 Conflict: конфликт с текущим состоянием; 422: данные понятны, но не прошли проверку; 429 Too Many Requests: слишком часто;
• 500 Internal Server Error: ошибка на сервере, а клиент ни при чём.

Выберите запрос и посмотрите на ответ. Два из запросов нарушают правила специально:

GET /items HTTP/1.1
Host: example.ru

200 OK
[{ "id": 1, "title": "Первое предложение" }, …]

/items:
  get:
    responses:
      '200': { description: Массив предложений }

Хорошая ошибка

Самое раздражающее в чужом API: ответ 500 без объяснений или код 200 с текстом «ошибка» внутри. Договоритесь, как выглядят ошибки, и держитесь этого везде. Минимум: правильный код состояния, короткий машинный код (invalid, not_found), по которому программа решает, что делать, и человеческий текст. Есть стандарт такого формата, RFC 9457 «Problem Details». Подробности (стек вызовов, пароли, пути на диске) в ответ не идут, они остаются в журнале сервера.

Версии, страницы и безопасность

• Версии. API меняется, а те, кто им пользуется, не успевают за вами. Поэтому номер версии кладут в адрес (/api/v1/items), и старая версия живёт, пока ею пользуются.
• Страницы и фильтры. Список из тысячи записей не отдают целиком: /items?page=2&limit=20, /items?q=межевание.
• HTTPS всегда, а особенно когда в запросе персональные данные (имя, телефон). Закон о персональных данных (152-ФЗ) ждёт от вас защиты, и первый шаг к ней шифрование.
• Проверка входа. Что угодно может прийти в запрос: сервер проверяет все поля, а не верит клиенту.
• Ограничение частоты, чтобы один злоумышленник не завалил сервер.

OpenAPI: договор в виде файла

Чтобы не объяснять API на словах, его описывают файлом по стандарту OpenAPI: в YAML или JSON перечислены адреса, методы, параметры, формы запросов и ответов. Формат вырос из проекта Swagger (2011), а с 2015 года развивается как открытый стандарт. По такому файлу автоматически получают интерактивную документацию (Swagger UI), заготовки программ-клиентов и проверку, что сервер отвечает как обещано.

paths:
  /requests:
    post:
      summary: Создать заявку из формы
      responses:
        '201':
          description: Заявка создана

Отступы пробелами важны: вложенность в YAML задаётся ими.

Как пробовать API

Три способа, ни одному не нужна специальная программа: вкладка «Сеть» в инструментах разработчика (смотреть настоящие запросы страницы), команда curl в терминале (curl https://example.ru/api/v1/items покажет ответ), и редактор Swagger (editor.swagger.io), в который можно вставить файл OpenAPI и нажать «Try it out».

Практика

Вы на сайте эпохи 2022 года, когда сайты общаются через API (это время Jamstack). Опишите API вашего проекта файлом OpenAPI: список ваших предложений, одно предложение и создание заявки из формы. Текст пишете в блоке pre прямо на странице, проверки читают его.

Три правила, которые проверка поймает: пути это существительные во множественном числе без глаголов; GET читает, а заявка создаётся POST и отвечает 201; описаны ответы 200, 400, 404 и общий формат ошибки. И одно правило, которое проверка не поймёт, но поймёт закон: персональные данные из формы принимаются только по HTTPS. Напишите это в описании заявки.

Что было не так раньше

До REST была мода на SOAP: обмен сообщениями в XML-конвертах, с огромными описаниями (WSDL) и инструментами, без которых их было не прочитать. А в простых API 2000-х годов всё шло через один адрес с параметром действия (/api.php?action=deleteItem&id=7), метод почти всегда был GET или POST без разбора, а ответ 200 приходил и при успехе, и при ошибке: просто с разным текстом. Любая программа, читавшая такой API, сначала писала разбор «что тут имели в виду».

Сегодняшнее соглашение скромнее, но надёжнее: адрес называет вещь, метод выражает действие, код говорит, получилось ли, а файл OpenAPI записывает всё это для людей и машин.