Повторение – мать учения

HTTP методы:

С помощью HTTP-методов вы сообщаете API, как вы хотите работать с ресурсами:

  • GET = чтение данных
  • POST = создание новых записей/ресурсов
  • PUT = обновление записей (целиком)
  • PATCH = обновление записей (частично)
  • DELETE = удаление записей
  • OPTIONS = получение списка опций для ресурса
  • HEAD = получение заголовков ресурса (ресурсов)

Коды ответов HTTP:

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

Статус
Значение
Что делать?
200, 201
Success – Успех. Запрос был успешно выполнен
Хлопаем в ладоши и идём по пиву
400
Bad request – Некорректный запрос. Сервер обнаружил в запросе клиента синтаксическую ошибку.
Проверяем параметры и тело запроса, используя спецификацию. Исправляем, повторяем попытку.
401, 403
Unauthorized, Forbidden – Не авторизован, Запрещено: недостаточно привилегий для доступа к ресурсу.
Проверяем спецификацию на предмет правильной авторизации.
404
Not Found – Не найден. Попытка вызова ресурса, который не существует.
Проверяем путь и параметры запроса на корректность и пробуем снова.
5xx
Server Error – Ошибка сервера. Случилось страшное!
Ищем разработчика сервиса и выясняем, что пошло не так.

Коды ответов HTTP можно разделить на следующие группы:

  • 1xx: Информационные
  • 2xx: Успешный вызов
  • 3xx: Перенаправление
  • 4xx: Ошибка клиента
  • 5xx: Ошибка сервера

Дополнительная литература: Википедия

JSON

Обычно API REST предполагают, что вы умеете читать JSON (Javascript Object Notation). Впрочем, и в самом деле, это вполне осуществимо:

JSON

Краткое освежение, как читать это:

  • "ключ" : "значение" – данные представлены парами ключ-значение. Ключ – это «имя» данных, а значение – их содержимое.
  • { ... } – все, что находится внутри фигурных скобок, называется Объектом. Пары ключ-значение внутри объекта логически принадлежат друг другу.
  • [ .. ] – все, что заключено в квадратные скобки, называется массивом. Массив похож на список. Массив используется для хранения нескольких объектов одного типа (например, списка клиентов)

Дополнительная литература: Википедия

Параметры

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

Тип параметра
Что делает
Пример
Body parameter
  • Передача данных в вызываемый API
  • Используется при POST и PUT вызовах
JSON Body 

{
  amount: 12.4,
  ccy: "EUR",
  type: "urgent"
}
Path parameter
  • Указывает на то, к какому ресурсу мы обращаемся
  • Является продолжением URL
/customer/123/account/4
Query parameter
  • Обычно используется для фильтрации результата
  • Записывается как пара ключ=значение
  • Используется амперсанд «&» для конкатенации нескольких параметров
/customer?level=detail
Header parameter
  • Используется для технических целей (например, для авторизации)
{"Authorization": "Bearer eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyR …}

Параметры могут быть указаны в нескольких местах:

  • Параметр пути: предоставляется как часть URL-адреса (/customer/{id}) — id — это параметр пути.
  • Параметр запроса: добавляется к URL-адресу (/customers?fields=firstName) — fields=firstName является параметром запроса.
  • Параметр тела запроса: предоставляется в полезной нагрузке во время вызова API — в наших примерах это всегда структура JSON.
  • Параметр заголовка: технические метаданные, используемые внутренним программным обеспечением для лучшего понимания типа запроса. В нашем курсе мы не используем параметры заголовка.