Инженерия ПО
API Design: REST, GraphQL, gRPC
Stripe API считается эталоном дизайна в индустрии - не потому что использует модные технологии, а потому что документация ясная, поведение предсказуемое и backward compatibility соблюдается годами. Плохое API design создаёт технический долг который невозможно исправить без breaking changes - тысячи клиентов зависят от текущего поведения.
- **Stripe API**: поддерживает версии API с 2014 года. Клиент зафиксировал версию - она работает годами без вынужденных миграций. Эталон backward compatibility
- **GitHub GraphQL API v4**: переход с REST v3 на GraphQL позволил получать данные для сложных запросов в 1-2 вызовах вместо 10+. Используется крупнейшими GitHub интеграциями
- **Google gRPC**: все внутренние сервисы Google общаются через gRPC с protobuf. Строгая типизация схемы позволяет автоматически генерировать клиенты для 10+ языков
REST Conventions
REST (Representational State Transfer) - архитектурный стиль определённый Roy Fielding в диссертации 2000 года. Ключевые ограничения: stateless (каждый запрос содержит всю информацию), uniform interface (ресурсы идентифицируются через URI, стандартные методы HTTP), cacheable. Stripe API - эталон REST дизайна: последовательное именование, предсказуемые паттерны, обратная совместимость.
HTTP методы определяют семантику операции: GET (чтение, idempotent, cacheable), POST (создание, не idempotent), PUT (полная замена, idempotent), PATCH (частичное обновление), DELETE (удаление, idempotent). Статус коды: 2xx (успех), 3xx (редирект), 4xx (client error), 5xx (server error). 200 OK vs 201 Created vs 204 No Content - детали имеют значение для client-side обработки.
API endpoint для отмены заказа. Какой дизайн лучше всего следует REST conventions?
GraphQL Schema
GraphQL создан Facebook в 2012 году для решения проблем REST с мобильными клиентами: over-fetching (REST возвращает все поля, клиент использует 3 из 20) и under-fetching (нужно 5 REST запросов для одного экрана). GraphQL позволяет клиенту точно указать какие поля нужны в одном запросе. GitHub переключил публичный API на GraphQL v4 - разработчики получают данные точнее.
Schema - контракт между клиентом и сервером, определяет все доступные типы и операции. Queries (чтение), Mutations (изменения), Subscriptions (real-time через WebSocket). N+1 проблема: query запрашивает 100 users, для каждого - их orders = 101 запрос к БД. DataLoader решает через batching: все запросы к orders за один цикл батчируются в один SQL WHERE id IN (...).
GraphQL query запрашивает 50 posts, каждый с author. Без оптимизации это делает 51 запрос к БД (1 + 50). Как решить N+1 проблему?
gRPC и Protocol Buffers
gRPC - high-performance RPC framework от Google, использует Protocol Buffers (protobuf) для сериализации и HTTP/2 для транспорта. Protobuf в 3-10 раз компактнее JSON, парсится быстрее. HTTP/2 даёт multiplexing (множество запросов по одному соединению) и bidirectional streaming. Google использует gRPC для inter-service communication: десятки миллиардов RPC вызовов в день.
gRPC типы: Unary (один запрос - один ответ, как HTTP), Server Streaming (один запрос - поток ответов, например: читать логи), Client Streaming (поток запросов - один ответ, например: загрузка файла по частям), Bidirectional Streaming (поток в обоих направлениях, например: real-time chat). gRPC лучше REST для внутренних микросервисных вызовов: типизация через .proto схему, генерация клиентского кода, меньше overhead.
Для какого сценария gRPC предпочтительнее REST?
API Versioning
API versioning - стратегия эволюции API без breaking changes для существующих клиентов. Подходы: URL versioning (/v1/, /v2/ - простой, явный, популярный), Header versioning (Accept: application/vnd.api+json;version=2), Query param (?version=2). Stripe годами поддерживает несколько версий API одновременно - клиент указывает версию при инициализации SDK и остаётся на ней до готовности мигрировать.
Breaking vs Non-breaking changes. Non-breaking (backwards compatible): добавление нового поля в response, новый optional параметр, новый endpoint. Breaking: удаление или переименование поля, изменение типа поля, изменение семантики (404 вместо пустого массива), изменение аутентификации. GraphQL и protobuf позволяют эволюцию схемы без explicit versioning: добавление полей backwards compatible, удаление - deprecation + grace period.
GraphQL заменяет REST и gRPC - это единственный современный подход
REST, GraphQL и gRPC решают разные проблемы. REST - стандарт для public API. GraphQL - когда клиентам нужна гибкость запросов. gRPC - высокопроизводительные внутренние сервисы
Netflix использует все три: GraphQL для Federated API Gateway, gRPC для внутренних сервисов, REST для legacy и простых public endpoints. Выбор определяется use case, не модностью
REST API изменяет тип поля `price` с String ('10.00') на Number (10.00). Это...
Связанные темы
API Design определяет контракт между сервисами и клиентами:
- Микросервисы: паттерны — API Gateway агрегирует REST/GraphQL/gRPC endpoints микросервисов в unified API для клиентов
- SRE: Site Reliability Engineering — SLO для API: p99 latency, error rate, availability - измеряются и контролируются на уровне API design
Вопросы для размышления
- Когда GraphQL создаёт больше проблем чем решает - примеры где REST был бы лучше?
- Как обеспечить backward compatibility при активной разработке API с множеством клиентов?
- gRPC строгая типизация через .proto - преимущество или ограничение при быстро меняющихся требованиях?