mufassall

Шпаргалка · Взаимодействие

Стили API

12 мин · Начальный · mufassall.dtwin.uz/ru/l/apis/

← Открыть урок

Проблема

Один экран приложения доставки еды, «Мои заказы», сначала на REST, потом на GraphQL, а между сервисами — gRPC. Где каждый стиль берёт слишком много или слишком мало и какие привычки нужны любому API: курсорная пагинация, версии и ключи идемпотентности.

Чему вы научитесь

  • Over-fetching, under-fetching и вызванные ими N+1 запросы
  • REST, GraphQL и gRPC: в чём хорош каждый на одной и той же функции
  • Курсор вместо OFFSET и новая версия вместо ломающего изменения
  • Idempotency-Key, который делает повторный POST безопасным
Итоговая сцена
15%20%15%

Диаграмма как код

Итоговая схема урока в виде текста: вставьте её в Jira, GitLab, GitHub, Notion или документацию, там Mermaid рисуется сам. Есть варианты для D2 и PlantUML (Confluence, IntelliJ).

Mermaid: схема

flowchart LR
  n_phone(["Приложение"])
  n_api["REST API"]
  n_db[("База")]
  n_gql["GraphQL-сервер"]
  n_pricing["Сервис цен"]
  n_phone --> n_api
  n_api --> n_db
  n_phone --> n_gql
  n_gql --> n_db
  n_gql --> n_pricing

Mermaid: последовательность запросов

sequenceDiagram
  participant n_phone as Приложение
  participant n_api as REST API
  participant n_gql as GraphQL-сервер
  participant n_db as База
  participant n_pricing as Сервис цен
  Note over n_phone,n_api: REST: один ресурс — один URL
  n_phone->>n_api: GET /v1/orders?limit=20 HTTP/1.1
  n_api-->>n_phone: HTTP/1.1 200 OK
  Note over n_phone,n_api: Under-fetching: 1 + 20 запросов
  n_phone->>n_api: phone network log: 21 requests, 2.6 s
  Note over n_phone,n_api: Пусть клиент выбирает поля
  n_phone->>n_api: GET /v1/orders?limit=20#38;fields=id,status#38;expand=restaurant HTTP/1.1
  n_api-->>n_phone: HTTP/1.1 200 OK
  Note over n_phone,n_gql: GraphQL: запрос пишет клиент
  n_phone->>n_gql: POST /graphql HTTP/1.1
  n_gql-->>n_phone: HTTP/1.1 200 OK
  Note over n_gql,n_db: N+1 переехал на сервер
  n_gql->>n_db: SELECT * FROM orders WHERE user_id = 'u_42' LIMIT 20#59;
  Note over n_gql,n_db: Собрать ID и спросить один раз
  n_gql->>n_db: SELECT id, name FROM restaurants
  n_db-->>n_gql: 14 rows
  Note over n_gql,n_pricing: gRPC между сервисами
  n_gql->>n_pricing: POST /pricing.v1.Pricing/Quote HTTP/2
  n_pricing-->>n_gql: HTTP/2 200
  Note over n_api,n_db: Страница 2 повторяет страницу 1
  n_api->>n_db: SELECT id, created_at FROM orders
  n_db-->>n_api: ord_962 #124; 2026-11-17 18:02
  Note over n_phone,n_api: Курсорная пагинация в /v2
  n_phone->>n_api: GET /v2/orders?limit=20#38;after=c_ord_962 HTTP/1.1
  n_api-->>n_phone: HTTP/1.1 200 OK
  Note over n_phone,n_api: Повтор создаёт второй заказ
  n_phone-xn_api: POST /v1/orders HTTP/1.1
  Note over n_phone,n_api: Idempotency-Key: на повтор — тот же ответ
  n_phone->>n_api: POST /v1/orders HTTP/1.1
  n_api-->>n_phone: HTTP/1.1 201 Created

D2

direction: right

n_phone: "Приложение" {
  shape: rectangle
}
n_api: "REST API" {
  shape: rectangle
}
n_db: "База" {
  shape: cylinder
}
n_gql: "GraphQL-сервер" {
  shape: rectangle
}
n_pricing: "Сервис цен" {
  shape: rectangle
}

n_phone -> n_api
n_api -> n_db
n_phone -> n_gql
n_gql -> n_db
n_gql -> n_pricing

PlantUML: последовательность запросов

@startuml
participant "Приложение" as n_phone
participant "REST API" as n_api
participant "GraphQL-сервер" as n_gql
database "База" as n_db
participant "Сервис цен" as n_pricing
note over n_phone, n_api : REST: один ресурс — один URL
n_phone -> n_api : GET /v1/orders?limit=20 HTTP/1.1
n_api --> n_phone : HTTP/1.1 200 OK
note over n_phone, n_api : Under-fetching: 1 + 20 запросов
n_phone -> n_api : phone network log: 21 requests, 2.6 s
note over n_phone, n_api : Пусть клиент выбирает поля
n_phone -> n_api : GET /v1/orders?limit=20&fields=id,status&expand=restaurant HTTP/1.1
n_api --> n_phone : HTTP/1.1 200 OK
note over n_phone, n_gql : GraphQL: запрос пишет клиент
n_phone -> n_gql : POST /graphql HTTP/1.1
n_gql --> n_phone : HTTP/1.1 200 OK
note over n_gql, n_db : N+1 переехал на сервер
n_gql -> n_db : SELECT * FROM orders WHERE user_id = 'u_42' LIMIT 20;
note over n_gql, n_db : Собрать ID и спросить один раз
n_gql -> n_db : SELECT id, name FROM restaurants
n_db --> n_gql : 14 rows
note over n_gql, n_pricing : gRPC между сервисами
n_gql -> n_pricing : POST /pricing.v1.Pricing/Quote HTTP/2
n_pricing --> n_gql : HTTP/2 200
note over n_api, n_db : Страница 2 повторяет страницу 1
n_api -> n_db : SELECT id, created_at FROM orders
n_db --> n_api : ord_962 | 2026-11-17 18:02
note over n_phone, n_api : Курсорная пагинация в /v2
n_phone -> n_api : GET /v2/orders?limit=20&after=c_ord_962 HTTP/1.1
n_api --> n_phone : HTTP/1.1 200 OK
note over n_phone, n_api : Повтор создаёт второй заказ
n_phone ->x n_api : [потеряно] POST /v1/orders HTTP/1.1
note over n_phone, n_api : Idempotency-Key: на повтор — тот же ответ
n_phone -> n_api : POST /v1/orders HTTP/1.1
n_api --> n_phone : HTTP/1.1 201 Created
@enduml

PlantUML: компоненты

@startuml
left to right direction
agent "Приложение" as n_phone
component "REST API" as n_api
database "База" as n_db
component "GraphQL-сервер" as n_gql
component "Сервис цен" as n_pricing
n_phone --> n_api
n_api --> n_db
n_phone --> n_gql
n_gql --> n_db
n_gql --> n_pricing
@enduml

Итог

Пять привычек для API.

1) REST прост и хорошо кешируется, но следите за N+1 и толстыми ответами. 2) GraphQL даёт выбор клиенту, но группируйте резолверы и ограничивайте стоимость запроса. 3) gRPC — для вызовов между своими сервисами. 4) Листайте курсором, ломающие изменения выпускайте новой версией. 5) Каждый создающий POST принимает Idempotency-Key.

Показатели: в начале и в конце

ПоказательВ началеВ конце
Запросов на экран11
Загрузка экрана180 мс210 мс
Данных на экран0,1 МБ0,0 МБ
Двойные заказы0/день0/день

Шаги

  1. Кейс REST: один ресурс — один URL

    Экрану «Мои заказы» для каждого из последних 20 заказов нужны статус и название ресторана.

  2. Проблема Under-fetching: 1 + 20 запросов

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

  3. Решение Пусть клиент выбирает поля

    REST API учится двум параметрам: fields перечисляет, что вернуть, а expand встраивает связанный объект.

  4. Кейс GraphQL: запрос пишет клиент

    GraphQL-сервер описывает все данные одной типизированной схемой.

  5. Проблема N+1 переехал на сервер

    Телефон делает один запрос, но GraphQL-сервер получает restaurant для каждого заказа отдельно.

  6. Решение Собрать ID и спросить один раз

    Теперь сервер собирает все ID ресторанов, нужные запросу, и спрашивает базу один раз через IN (...).

  7. Кейс gRPC между сервисами

    Экран показывает ещё стоимость и время доставки из сервиса цен.

  8. Проблема Страница 2 повторяет страницу 1

    Старые заказы подгружаются при прокрутке через OFFSET 20.

  9. Решение Курсорная пагинация в /v2

    Страница теперь говорит, где она закончилась, а не сколько строк пропустить: «дай 20 заказов после этого».

  10. Проблема Повтор создаёт второй заказ

    Пользователь жмёт «Заказать».

  11. Решение Idempotency-Key: на повтор — тот же ответ

    Перед первой попыткой приложение генерирует случайный ключ и отправляет его с каждым повтором этого заказа.

  12. Итоги Итоги

    Пять привычек для API.

Термины

REST
У каждого ресурса один URL и стандартные HTTP-методы. Просто и хорошо кешируется, но легко приводит к over-fetching, under-fetching и N+1 запросам.
GraphQL
Клиент сам пишет в запросе, какие поля ему нужны, и получает их одним вызовом. N+1 переезжает на сервер, поэтому резолверы группируют, а стоимость запроса ограничивают.
gRPC
Быстрый RPC-протокол со строгой схемой и бинарным форматом. Подходит для внутренних вызовов между своими сервисами.
Курсорная пагинация
Следующую страницу просят не через OFFSET, а курсором, указывающим на последнюю показанную запись. Новые записи не вызывают повторов и пропусков.
Idempotency-Key
Уникальный ключ, который клиент добавляет к каждому запросу на создание. Сервер запоминает ключ и на повтор возвращает тот же ответ, не создавая второй заказ.