APIСтандартизация
тема 1 Открыть слайдами →

Часть 2 из 15 · слайды 4–8

Запрос, ответ, ресурс

Правила пишутся для обмена сообщениями между программами, поэтому сначала разберём один такой обмен.

  1. 4API — граница между программами
  2. 5Что происходит при обращении к API
  3. 6Анатомия HTTP-запроса
  4. 7Анатомия ответа
  5. 8REST работает вокруг ресурсов

4API — граница между программами

API (Application Programming Interface) — интерфейс, через который одна программа взаимодействует с другой.

Например, веб-интерфейс службы поддержки запрашивает у сервера список обращений:

Frontend→GET /api/v1/tickets→Backend→JSON

Клиенту не требуется знать:

  • язык, на котором написан backend;
  • структуру базы данных;
  • внутренние классы;
  • алгоритмы сервера.

Клиент должен знать только контракт API.

  1. FRONTENDHTTP
  2. PUBLIC APIто, что видит клиент
  3. INTERNAL CODE · DATABASEможно менять, не нарушая контракт

5Что происходит при обращении к API

Обмен всегда состоит из двух сообщений: клиент отправляет HTTP request, сервер обрабатывает его и возвращает HTTP response.

HTTP request
GET /api/v1/tickets/42
HTTP response
200 OK
Content-Type: application/json

{
  "id": 42,
  "title": "Не работает VPN",
  "status": "open"
}

Здесь клиент просит обращение с идентификатором 42. Сервер отвечает кодом 200 OK, сообщает формат тела и передаёт само обращение в JSON.

  1. CLIENT
  2. HTTP REQUESTметод и адрес
  3. SERVER
  4. HTTP RESPONSEкод, заголовки, тело
  5. CLIENT

6Анатомия HTTP-запроса

HTTP request может содержать метод, URL, заголовки, query parameters и тело. Нажмите на часть в легенде, чтобы увидеть её в запросе.

POST
method
/api/v1/tickets
url
Authorization: Bearer TOKEN
header
Content-Type: application/json
header
{
  "title": "Не работает VPN",
  "description": "Ошибка после обновления"
}
body

В настоящем сообщении метод и путь записаны в одной строке: POST /api/v1/tickets HTTP/1.1. Здесь они разнесены, чтобы подписать каждую часть отдельно.

7Анатомия ответа

Ответ сервера содержит status code, заголовки и тело.

201 Created
status
Location: /api/v1/tickets/8d45...
header
Content-Type: application/json
header
{
  "id": "8d45...",
  "title": "Не работает VPN",
  "status": "open"
}
body

201 сообщает машине результат операции, а JSON содержит данные созданного ресурса.

8REST работает вокруг ресурсов

Ресурс — сущность предметной области, которой API предоставляет адрес.

В нашем проекте ресурс — Ticket, обращение в службу поддержки.

ЧтоАдрес
Коллекция обращений/api/v1/tickets
Конкретное обращение/api/v1/tickets/{ticket_id}

URL описывает, что это за ресурс, а HTTP-метод — что с ним требуется сделать.

tickets
│
├── 41
├── 42
└── 43

Кадр крупным планом