Что такое REST API: простое объяснение с примерами

Коротко о главном

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

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

Ресурсы и эндпоинты

Ресурс — это любая сущность, с которой работает система: товар, категория, заказ, пользователь.

Эндпоинт — адрес, по которому доступен ресурс:

• /products — все товары (коллекция);
• /products/42 — конкретный товар с id 42;
• /categories/5/products — товары категории 5.

В адресах используются существительные, а не глаголы. Не /getProducts, а /products. Что сделать с ресурсом, говорит HTTP-метод.

HTTP-методы: что делаем с ресурсом

Один и тот же адрес /products/42 с разными методами означает разные действия. Это и делает REST API предсказуемым.

JSON: формат данных

Чаще всего сервер и клиент обмениваются данными в формате JSON — простом текстовом формате, который легко читают и люди, и программы.

Запрос на создание товара:

POST /products
Content-Type: application/json

{
  "name": "Чайник электрический",
  "price": 250000,
  "categoryId": 5
}

Ответ сервера:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 43,
  "name": "Чайник электрический",
  "price": 250000,
  "categoryId": 5
}

Stateless: сервер не помнит прошлых запросов

Принцип stateless означает, что каждый запрос самодостаточен. Сервер не хранит «сессию разговора» между запросами — клиент каждый раз передаёт всё необходимое, например токен авторизации в заголовке:

GET /orders
Authorization: Bearer <token>

Зачем это нужно: любой из нескольких серверов может обработать любой запрос. Систему проще масштабировать и восстанавливать после сбоев.

Коды ответов: результат одним числом

Сервер сообщает итог трёхзначным кодом:

• 2xx — успех: 200 OK, 201 Created, 204 No Content.
• 3xx — перенаправление.
• 4xx — ошибка клиента: 400 Bad Request (неверные данные), 401 Unauthorized (не авторизован), 404 Not Found (ресурса нет).
• 5xx — ошибка сервера: 500 Internal Server Error.

Клиент сначала смотрит на код и только потом — на тело ответа.

Где вы встречаете REST API

• Мобильное приложение загружает ленту и корзину.
• Сайт принимает оплату через платёжный сервис.
• CRM получает заявки с сайта.
• Склад синхронизирует остатки с маркетплейсом.

Почти любая интеграция между системами сегодня — это вызовы API, и REST среди них самый распространённый стиль.

Частые заблуждения

• «REST — это просто JSON по HTTP». Важны ещё ресурсы, правильные методы и коды ответов.
• «Всё можно делать через POST». Можно, но тогда теряется предсказуемость, кэширование и понятность для других разработчиков.
• «Ошибку можно вернуть с кодом 200». Это ломает логику клиентов: они считают запрос успешным.