Как устроен REST API и как к нему обращаться

Что это такое

Способ, которым одна программа обращается к другой. Не человек в браузере, а код: мобильное приложение к серверу, страница к серверу, одна система к другой.

Основная идея подхода: у каждой сущности есть адрес, а действие над ней определяется методом запроса.

Методы

Пять, которые нужны на практике:

GET — получить. Не должен ничего менять.
POST — создать новое.
PUT — заменить целиком.
PATCH — изменить частично.
DELETE — удалить.

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

Адреса

Приняты такие правила:

GET    /notes         список заметок
GET    /notes/42      одна заметка
POST   /notes         создать заметку
PATCH  /notes/42      изменить заметку
DELETE /notes/42      удалить заметку

Существительные во множественном числе, действие выражается методом, а не адресом. Адрес вида «/getNotes» противоречит подходу, хотя технически работает.

Коды ответов

По первой цифре понятно, что случилось:

2xx — получилось. 200 — успех, 201 — создано, 204 — успех без содержимого.
3xx — перенаправление.
4xx — ошибка того, кто обратился. 400 — неверный запрос, 401 — не представился, 403 — представился, но нельзя, 404 — не найдено, 429 — слишком часто.
5xx — ошибка на сервере. Ваш запрос ни при чём.

Разницу между 401 и 403 спрашивают на собеседованиях почти всегда. Первое — «кто вы?», второе — «я знаю, кто вы, и вам сюда нельзя».

Как читать чужую документацию

Порядок:

Найдите базовый адрес — общее начало всех обращений.
Посмотрите, нужен ли ключ и как его передавать: обычно в заголовке.
Найдите нужный раздел и посмотрите: метод, адрес, обязательные параметры.
Посмотрите пример ответа. Это важнее описания полей: сразу видно структуру.
Проверьте ограничения по частоте обращений.

Хорошая документация даёт готовый пример запроса, который можно скопировать и выполнить.

Как обратиться из кода

async function loadNotes() {
  const res = await fetch("https://example.com/api/notes", {
    headers: { Authorization: "Bearer " + token },
  });

  if (!res.ok) {
    throw new Error("Сервер ответил " + res.status);
  }

  return res.json();
}

Ключевая деталь: проверка успешности обязательна. Запрос, вернувший ошибку, не считается неудачным сам по себе — надо смотреть на код ответа. Забытая проверка приводит к загадочным ошибкам разбора, потому что вместо данных пришло описание ошибки.

Частые ошибки

Ключ в коде. Всё, что попало в открытый репозиторий, считается раскрытым. Ключи — в переменные окружения.

Нет обработки ошибок. Сервер может не ответить, ответить ошибкой, ответить не тем. Все три случая должны быть предусмотрены.

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

Игнорирование ограничений по частоте. Получите запрет на обращения и будете долго выяснять, почему всё сломалось.

Отправка данных не в том виде. Если сервер ждёт данные в формате обмена, надо и заголовок соответствующий поставить, и данные преобразовать.

Как потренироваться

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

Это классическое учебное задание, и оно же — половина работы фронтенд-разработчика.