Шпаргалка · Взаимодействие
Стили API
Проблема
Один экран приложения доставки еды, «Мои заказы», сначала на REST, потом на GraphQL, а между сервисами — gRPC. Где каждый стиль берёт слишком много или слишком мало и какие привычки нужны любому API: курсорная пагинация, версии и ключи идемпотентности.
Чему вы научитесь
- Over-fetching, under-fetching и вызванные ими N+1 запросы
- REST, GraphQL и gRPC: в чём хорош каждый на одной и той же функции
- Курсор вместо
OFFSETи новая версия вместо ломающего изменения Idempotency-Key, который делает повторныйPOSTбезопасным
Диаграмма как код
Итоговая схема урока в виде текста: вставьте её в 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_pricingMermaid: последовательность запросов
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 CreatedD2
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_pricingPlantUML: последовательность запросов
@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
@endumlPlantUML: компоненты
@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.
Показатели: в начале и в конце
| Показатель | В начале | В конце |
|---|---|---|
| Запросов на экран | 1 | 1 |
| Загрузка экрана | 180 мс | 210 мс |
| Данных на экран | 0,1 МБ | 0,0 МБ |
| Двойные заказы | 0/день | 0/день |
Шаги
- Кейс REST: один ресурс — один URL
Экрану «Мои заказы» для каждого из последних 20 заказов нужны статус и название ресторана.
- Проблема Under-fetching: 1 + 20 запросов
Названия нет, поэтому приложение запрашивает каждый ресторан отдельно: один запрос за списком и ещё двадцать, по одному на заказ.
- Решение Пусть клиент выбирает поля
REST API учится двум параметрам:
fieldsперечисляет, что вернуть, аexpandвстраивает связанный объект. - Кейс GraphQL: запрос пишет клиент
GraphQL-сервер описывает все данные одной типизированной схемой.
- Проблема N+1 переехал на сервер
Телефон делает один запрос, но GraphQL-сервер получает
restaurantдля каждого заказа отдельно. - Решение Собрать ID и спросить один раз
Теперь сервер собирает все ID ресторанов, нужные запросу, и спрашивает базу один раз через
IN (...). - Кейс gRPC между сервисами
Экран показывает ещё стоимость и время доставки из сервиса цен.
- Проблема Страница 2 повторяет страницу 1
Старые заказы подгружаются при прокрутке через
OFFSET 20. - Решение Курсорная пагинация в
/v2Страница теперь говорит, где она закончилась, а не сколько строк пропустить: «дай 20 заказов после этого».
- Проблема Повтор создаёт второй заказ
Пользователь жмёт «Заказать».
- Решение
Idempotency-Key: на повтор — тот же ответПеред первой попыткой приложение генерирует случайный ключ и отправляет его с каждым повтором этого заказа.
- Итоги Итоги
Пять привычек для API.
Термины
- REST
- У каждого ресурса один URL и стандартные HTTP-методы. Просто и хорошо кешируется, но легко приводит к over-fetching, under-fetching и N+1 запросам.
- GraphQL
- Клиент сам пишет в запросе, какие поля ему нужны, и получает их одним вызовом. N+1 переезжает на сервер, поэтому резолверы группируют, а стоимость запроса ограничивают.
- gRPC
- Быстрый RPC-протокол со строгой схемой и бинарным форматом. Подходит для внутренних вызовов между своими сервисами.
- Курсорная пагинация
- Следующую страницу просят не через OFFSET, а курсором, указывающим на последнюю показанную запись. Новые записи не вызывают повторов и пропусков.
- Idempotency-Key
- Уникальный ключ, который клиент добавляет к каждому запросу на создание. Сервер запоминает ключ и на повтор возвращает тот же ответ, не создавая второй заказ.