Привет, хабровчане!
Я Дима, Backend-разработчик на Go.
Расскажу о GraphQL, сравню с REST. Разберемся в плюсах и минусах каждого подхода к проектированию API. Выбираем лучший для вашего проекта!
Распространенность и интеграция
В 2015 году Facebook представил GraphQL. С тех пор эта технология набирает популярность, но REST остается лидером. По данным Postman на 2024 год, GraphQL используют 29% разработчиков, REST — 90%.
Если заранее неизвестны потребители API, лучше выбрать REST — он проще и популярнее:
Разработчикам, знакомым с HTTP, легко освоить REST. Он использует стандартные HTTP-методы и принципы.
REST API можно реализовать на любом языке, поддерживающем HTTP, без дополнительных слоев.
REST — проверенная технология с сильным сообществом и множеством готовых инструментов.
Получение данных
GraphQL позволяет клиентам запрашивать только нужные данные, избегая избыточного или недостаточного получения. Это повышает эффективность сетевых запросов: передаются только необходимые данные.
Рассмотрим пример. Есть сущность «Игрушка» (Toy), которую создает «Мастер» (Master), привязанный к «Пользователю» (User). У игрушки также есть «Категория» (Category) и «Теги» (Tags).
GraphQL позволяет получить все данные одним запросом:
POST http://localhost:8080/query
Content-Type: application/json
query getToy {
toy(id: 1) {
id
name
description
price
quantity
createdAt
updatedAt
category {
id
name
}
tags {
id
name
}
master {
id
info
user {
id
displayName
email
phone
}
}
}
}
В случае REST API потребовалась бы серия запросов:
GET http://localhost:8080/toys/1 - Получаем игрушку по ID
GET http://localhost:8080/categories/2 - Получаем категорию игрушки по ID, который взяли из объекта игрушки
GET http://localhost:8080/tags?id=1&id=2&id=3 - Получаем теги игрушки по ID, которые взяли из объекта игрушки
GET http://localhost:8080/masters/3 - Получаем мастера игрушки по ID, который взяли из объекта игрушки
GET http://localhost:8080/users/4 - Получаем пользователя, к которому привязан мастер, по ID, который взяли из объекта мастера
В приложениях со сложными связями между доменами GraphQL упрощает получение данных: один запрос вместо пяти (в примере). Кроме того, можно исключить ненужные поля, например, createdAt и updatedAt. GraphQL возвращает только то, что нужно.
Тестирование
Интеграционное тестирование на разных языках программирования отличается, поэтому посмотрим на примере регистрации пользователя через Postman.
Запрос к GraphQL API:
Запрос к REST API:
Пока разница невелика, но GraphQL уже выглядит сложнее. Основная сложность — отправка файлов. Сравним запросы на создание игрушки.
Запрос к GraphQL API:
В поле operations нужно вставить запрос:
{
"query": "mutation CreateToy($input: CreateToyInput!) { createToy(input: $input) }",
"variables": {
"input": {
"categoryId": "123",
"name": "Example Toy",
"description": "This is an example toy",
"price": 19.99,
"quantity": 10,
"attachments": [null] // Указываем null для файлов. Сколько файлов - столько null
}
}
}
Поле map связывает переменные файла с attachments в operations, чтобы файлы отправились:
{
"0": ["variables.input.attachments.0"]
}
Каждый файл нужно прикрепить в отдельном поле, имя которого соответствует ключу из map.
В REST API все параметры для создания игрушки указываются проще:
Версионирование
GraphQL использует одну версию endpoint. Изменения вносятся в схему без явного версионирования API, что упрощает развитие.
REST API нужно версионировать для безопасных изменений. Обычно это делается в URL, например: http://localhost:8080/v1/toys.
Ошибки и коды ответа
GraphQL всегда отвечает кодом 200 OK, даже при ошибках. Информацию об ошибке ищите в поле errors JSON-ответа. Клиент не может проверить статус по HTTP-коду и вынужден анализировать тело ответа.
REST использует стандартные HTTP-коды (400, 404, 500) для обозначения результата. Это делает обработку ошибок в REST более наглядной
Заключение
Выбор между GraphQL и REST — это вопрос потребностей проекта. REST лидирует благодаря простоте, популярности и развитым инструментам. GraphQL же гибче в запросах: запрашиваем только нужное, не перегружаем сеть лишним, что важно для сложных приложений.
Тестировать GraphQL сложнее, особенно с файлами: больше настроек в запросах, чем в REST. GraphQL проще версионировать — меняем схему, и всё, а в REST приходится менять URL. Наконец, GraphQL всегда отвечает кодом 200 и сообщает об ошибках в теле ответа, а REST использует стандартные коды ошибок, что делает их более заметными.
