Для интеграции и разработки систем в основном используется REST API, но, помимо него, есть и другие программные интерфейсы, как GraphQL. Они менее популярны, но не менее актуальны.
В этой статье я хочу передать вам пошаговую инструкцию по тестированию открытого GraphQL API через Postman. С её помощью вы познакомитесь с основами GraphQL на практике.
Статья постоена по принципу:
сначала практика: каждый шаг инструкции сопровождается комментариями, которые помогут понять главные принципы работы API (будет много сравнений с REST AP);
потом теория: в конце статьи приводится развернутый обзор теории.
Материал будет полезен системным аналитикам, разработчикам и тестировщикам, которые хотят разобраться в структуре запросов и ответов, понять ключевые принципы работы с GraphQL, подходы к его проектированию, а также научиться интегрироваться с сервисами, предоставляющими GraphQL интерфейс для взаимодействия.
Оглавление:
Пошаговая инструкция по тестированию GraphQL через Postman
В этом руководстве мы будем тестировать Rick And Morty GraphQL API, созданный по мотивам одноименного анимационного сериала "Рик и Морти" (Rick And Morty). Если вы знакомы с ним, то это прекрасно!
Ссылка на документацию: https://rickandmortyapi.com/documentation
Откройте её перед началом работы в соседней вкладке браузера, как и Postman.
Эта документация поможет вам познакомиться с ресурсами Rick and Morty API и покажет, как делать различные запросы к GraphQL API, чтобы вы могли максимально эффективно использовать его.
В ходе практики мы будем получать данные о персонажах, локациях и эпизодах сериала.
P.S. Обратите внимание, что для сопоставления есть отдельная документация на REST API, которую можно сравнить с GraphQL.
Шаг 1. Откройте Postman и создайте Workspace
Если вы ранее не работали с Postman или нужно освежить знания, то начать стоит с практики по HTTP API.
Инструкция:
Postman: Практическое руководство с примером тестирования открытого API.
В самом начале есть инструкция по созданию Workspace (рабочего пространства).
Шаг 2. Создайте новый GraphQL запрос
(1) Нажмите "+", чтобы добавить новый запрос. По умолчанию, обычно, создается HTTP, если до этого вы не тестировали другие виды API.
(2) Выберите вид API - GraphQL.
Шаг 2. Настройте эндпоинт
Согласно API-документации Rick and Morty: https://rickandmortyapi.com/graphql
После настройки вы увидите, как автоматически подгрузилась схема данных API с комментариями по каждому полю.
Первые важные выводы:
Документация может быть встроена в описание схемы API.
Вау, не надо все вручную переносить в Postman для тестирования запросов и угадывать URL. Всё доступно сразу. Можно не бояться потерять какие-то параметры запроса, что особенно актуально для JSON / XML и подобных форматов.
Шаг 3. Пробуем выполнить запрос (неудачно)
(1) Не глядя в документацию, пробуем выделить первую "галочку" в списке предложенных query-параметров.
(2) Видим в правой панели автоматически сформированный запрос, с выделением красным ошибкой. Это область с описанием тела запроса.
Запрос имеет тип Query - получение данных.
Причина ошибки, которую видим сразу после установки "галочки": нужен id персонажа для получения информации о нем.
Теперь немного теории:
Запросы в GraphQL делятся на три вида:
Query - запросы на получение данных.
Можно увидеть, что перед перечислением запросов character, characters, charactersByIds и других есть заголовок "Query" группы запросов.
По сути это доступные нам эндпоинты.Mutation - мутация, предназначена для создания, изменения и удаления данных.
Аналог POST, PUT, PATCH, DELETE в REST API.
В данном API отсутствуют такие методы, но в конце подскажу где их можно найти.Subscription - подписка на обновление данных в реальном времени.
Такого механизма нет в REST, который работает на основе HTTP.
В этом случае GraphQL использует WebSocket соединение с сервером.
В данном API такие методы тоже отсутствуют.Получается, что Query и Mutation работают на основе протокола HTTP, а методы Subscription на основе протокола WebSocket.
Несмотря на наличие ошибки, попробуем выполнить запрос на получение данных о персонаже.
(1) Нажимаем кнопку "Query" для отправки запроса на сервер.
(2) Получаем ошибку HTTP-400
(плохой запрос, ошибка на стороне вызывающего - клиента API).
Для вызова этого запроса нам нужно знать id персонажа, данные о котором хотим получить. Поле ввода id есть в "зоне документации", слева, где мы можем настраивать запрос.
Шаг 4. Настраиваем запрос "Получение списка персонажей"
Чтобы знать id персонажей о которых запрашивать информацию, надо получить их список. За это отвечает запрос Сharacters
. Выполним его.
(1) В "панели документации" ставим галочку на characters.
После этого будет предсоздана структура запроса в "зоне кода" запроса.
(2) Т.к. список имеет вложенную структуру, то раскрываем её и ставим дополнительно галочку на results
.
В "зоне кода" доработан запрос.
(3) Обратите внимание как сопоставляются параметры документации с параметрами запроса.
Важные выводы:
Именование запросов на получение данных строится по следующим правилам:
получить один объект - Object (Character, Location, Episode и другие),
получить список объектов - Objects (Characters, Locations, Episodes и другие).
Именование объектов данных, которые возвращаются внутри запросов:
получить один объект - object,
получить список объектов - Objects.
Принцип построения запроса в GraphQL API:
тип запроса
<Название запроса (не обяз)
> {
<название главного объекта, возвращаемого по запросу
> {
<описание структуры ответа - возвразаемых объектов и параметров
>
}
Похоже на JSON, но это не он. Это формат запроса GraphQL.
Основные отличия:
нет , (запятых) в конце строк,
есть префикс
query,
отвечающий за тип запроса.В запросе на получение данных есть body (тело) - описание структуры ответа, который мы хотим получить. В REST API, если говорить о методе GET, оно отсутствует.
Шаг 5. Получаем ответ - массив результатов
Сопоставьте структуру запроса и тело ответа. То, как вы описали запрос, в такой структуре и пришел ответ.
На что следуюет обратить внимание:
Тело ответа в формате JSON.
вложенность объектов {},
массив [].
Код ответа HTTP-200 (в запросе на создание данных тоже будет HTTP-200, не HTTP-201.
То, что ответ начинается с "data" - это решение этих разработчиков. Абсолютно не обязательно, что ответ должен быть оформлен так. На мой взгляд в этом API переборщили с уровнями вложенности для структуры данных.
Шаг 6. Адаптируем запрос под нужды клиента
GraphQL нужен, чтобы оптимизировать трафик между клиентом API и сервером, который его предоставляет:
уменьшать количество запросов и ответов от сервера,
уменьшать объем данных, получаемый от сервера.
И если в REST API на список персонажей нам всегда будет приходить одинаковый JSON, с заложенным и заранее определенным в логике API набором данных, то в GraphQL мы можем настроить свою структуру ответа. Это значит, что мы можем увеличить или уменьшить количество параметров, которые хотим получать.
Это особенно актуально, когда в веб-приложении надо показать больше данных, а в мобильном приложении меньше.
Настраиваем в запросе для списка персонажей получение только id
, name
и status
. Получаем соответствующий ответ.
Шаг 7. Элементы пагинации - постраничный возврат результатов
В настройках запроса Characters есть page
. Это элемент пагинации. Аналогичные названия элементов пагинации в REST API: page, offset, count
/ limit, offset, count
. Подробнее про то, как работают элементы пагинации можно почитать здесь.
Задаем значение 1. Выполняем запрос. И получаем тот же результат, что и в предыдущем случае - те же 20 элементов списка.
Чтобы переключаться между страницами, давайте узнаем сколько их всего. По документации видно, что полную информацию по элементам пагинации можно найти во вложенном объекте info
:
count - общее количество записей (в ответе их 826! крутая тестовая база)
limit - максимальное количество элементов на страницу (вот почему их каждый раз по 20 получаем)
next - номер следующей страницы (крутое решение для элемента пагинации!)
prev - номер предыдущей страницы результатов.
В полученном ответе по странице 1 видим всё те же первые 20 результатов, но с дополнительным объектом info
после списка.
Запрашивам страницу page: 4
и видим, что результаты в возвращенном списке (массиве) персонажей поменялись. Теперь отображаются персонажи только 4-й страницы данных - с 61 по 80.
(1) Указываем настройку для элемента пагинации, которая влияет на результат.
(2) Сопоставляем структуру результат
Важные выводы:
Обратите внимание на то, что настраиваемые параметры запроса (фильтры) передаются в скобках, сразу после названия главного объекта.
characters(page: 4) { ..... }
Шаг 8. Вложенные объекты
Для каждого персонажа в списке поддержан возврат расширенной информации по эпизодам и локациям, в которых они участвовали.
Параметры во вложенных объектах episodes
и locations
, которые мы можем добавить в ответ, также можно настроить и возвращать только часть данных о них.
Код Query-запроса на получение списка персонажей с вложенными в них объектами - локации и эпизоды
query Characters {
characters(page: 4) {
results {
id
name
image
location {
id
created
name
}
episode {
id
name
air_date
episode
created
}
}
info {
count
pages
next
prev
}
}
}
Шаг 9. Два списка за один запрос
А что, если мне на страницу надо одновременно вывести несколько списков? Такое бывает полезно на формах поиска с настраиваемыми фильтрами.
Давайте попробуем вернуть список персонажей characters
и локаций locations
за один запрос.
В REST API такое просто невозможно и это противоречит здравому смыслу при проектировании структуры ответа на запрос :) Но GraphQL в этом плане гибкий и можно почти всё, что позволяет разработанная схема данных.
Код Query-запроса на получение списка персонажей с их локациями И локаций эпизода (два независимых массива)
query Characters {
characters(page: 4) {
results {
id
name
image
location {
id
created
name
}
episode {
id
name
air_date
episode
created
}
}
info {
count
pages
next
prev
}
}
locations {
results {
id
name
type
dimension
created
}
info {
count
pages
next
prev
}
}
}
А что, если в конец добавть не второй список, а описание конкретного персонажа character
с id = 189
? Так тоже можно. Всё, что пожелаем.
(1) Добавляем character
с id = 189
в запрос. Выполняем его.
(2) Получаем ответ, где в конце списка персонажей отдельно расположилась информация об одном конкретном персонаже, согласно описанной нами конструкции.
Запрос на получение списка персонажей + данных одного персонажа в конце
query Characters {
characters(filter: { name: "Rick", status: "Ali" }) {
results {
id
name
created
status
}
info {
count
pages
next
prev
}
}
character(id: "189") {
id
name
status
species
type
gender
image
created
}
}
Шаг 10. Настройка фильтров
В запросе списка персонажей также можно настроить фильтры. Например, по имени персонажа.
(1) Можно настроить фильтр "Имя" в зоне документации.
(2) По конструкции запроса фильтр, как настраиваемый параметр, появился там же, где и элементы пагинации. Но, т.к. фильтр имеет вложенные параметры, то описывается иначе.
characters(filter: { name: null, status: null }) { ... }
(3) Так как я ввела имя "Рик" на русском, то получили пустой результат.
Обратить внимание:
В GraphQL и в REST API одинаковый подход в плане хорошего дизайна - для пустого результата на запрос с фильтрами возвращать пустой список, а не ошибку HTTP-400/HTTP-404.
Это необязательное правило, но довольно распространенный стандарт отрасли.
А теперь давайте настроим фильтр имени нормально, на английском. Получили результаты запроса.
Добавим еще один фильтр по статусу персонажа, чтобы посмотреть как выглядят два фильтра в одном запросе.
Обращаем внимание, что в этом API логика работы фильтра на статус делает поиск по части наименования статуса Ali
(полное - Alive
). Это особенность именно этого API, но не GraphQL.
А теперь делаем совсем сложный запрос:
(1) Настраиваем одновременно элемент пагинации page и фильтры.
(2) Смотрим на структуру полученного запроса - часть с параметрами.
Выполняем запрос.
(3) Получаем успешный ответ HTTP-200 - результаты найдены.
(4) Структура ответа соответствует тому, что описано в результате "results"
.
Тестирование HTTP-запросов GraphQL
GraphQL работает на основе протокола HTTP, поэтому еще один вариант - тестировать HTTP-запросы в Postman.
Шаг 11. Создаем новый HTTP-запрос в Postman
(1) Добавляем новый запрос через иконку "+".
(2) Выбираем протокол HTTP.
Шаг 12. Настраиваем HTTP-запрос
(1) Вводим URL согласно документации: https://rickandmortyapi.com/graphql. Выбираем метод POST.
(2) Проверяем, что схема подгружена.
(3) Устанавливаем в разделе Body для запроса тело GraphQL (для REST API мы тут обычно выбираем raw).
(4) Копируем тело запроса на получение одного персонажа по id.
query Character {
character(id: "187") {
id
name
status
species
type
gender
image
created
}
}
(5) Вызываем запрос - нажимаем на кнопку "Send".
(6) Получаем код ответа - HTTP-200 (успех).
(7) В теле ответа видим запрошенную нами информацию.
Если выбрать метод GET, то выполнения запроса завершится ошибкой, так как тело запроса в GET обрезается на уровне протокола HTTP.
(1) Выбираем тип метода GET.
(5) Получаем ответ HTTP-204 - пустой результат.
(6) Пустое тело ответа.
Важный вывод:
GraphQL работает на основе метода HTTP POST.
Есть исключения, когда можно сделать GET вызов, но это исключения.
Шаг 12. Продолжаем исследовать API самостоятельно
Попробуйте поменять порядок параметров в структуре запроса GraphQL / HTTP.
Убедитсь в том, что структура ответа тоже поменялась.
Важный вывод:
В запросе GraphQL важен порядок передачи параметров, в то время как в REST API JSON это не принциписально.
Шаг 13. Продолжаем исследовать API самостоятельно
Коллеги, начало в работе с GraphQL положено. Предлагаю продолжать изучать тему.
Попрактикуйтесь еще с API Rick and Morty.
Задания для вас, пробуйте писать код для них самостоятельно:Получить список эпизодов без вложенных объектов.
Получить список эпизодов с вложенными объектами.
Получить списки персонажей, локаций и эпизодов.
Получить информацию о локации.
Поменять порядок полей в информации о локации.
Получить список локаций с применением всех возможных фильтров.
В конце этой статьи я привожу подборку открытых GraphQL API. Из них настоятельно рекомендую посмотреть Shopify, где можно самостоятельно изучить мутации и работу с авторизацией в GraphQL.
Конкретные части API-документации Shopify, которые я рекомендую посмотреть:
Важное про GraphQL:
Обратите внимание на нейминг методов в мутациях (
orderCreate
,orderDelete
,orderCancel
и другие). Это принципальное отличие от именование методов в REST API, где за часть создать, изменить или удалить отвечают HTTP-методы.
Бонус
На случай, если что-то не получилось, я сохранила для вас несколько запросов в этих Postman-коллекциях. Пользуйтесь.
ТЕОРИЯ
GraphQL - что это в сравнении с REST API
Новый API легче всего изучать, сравнивая его с тем, в котором вы уже хорошо разбираетесь и понимаете все нюансы, как в интеграции через него, так и в проектировании методов с нуля.
Когда я изучала GraphQL, я опиралась на свой опыт работы с REST API.
В этой статье я собрала ключевые знания, которые помогают мне как проектировать GraphQL методы с нуля, так и интегрироваться с системами, использующими GraphQL.
1. Основная информация
GraphQL | REST API | |
Определение | Язык запросов для API, который позволяет клиентам запрашивать только те данные, которые им нужны. | Архитектурный стиль, который определяет, по каким правилам приложения должны обмениваться данными между собой. |
Год и история | 2015 | 2000 |
Протокол | HTTP | HTTP |
Основные методы | GET, POST | GET, POST, PATCH, PUT, DELETE |
Если вы не до конца понимаете как HTTP и REST связаны между собой, то прежде чем идти далее я рекомендую познакомиться со статьей Протокол HTTP и его связь с REST API.
Общие принципы GraphQL
Запросы к серверу используются для получения данных (query), а мутации (mutation) — для их создания изменения.
Все запросы и мутации выполняются к одному URL.
Сервер GraphQL определяет схему, которая описывает типы данных и операции, доступные для клиентов.
Клиенты могут запрашивать только те данные, которые им нужны. Это уменьшает объем передаваемых данных и улучшает производительность.
Особенности и отличия от других API
В отличие от REST, где нужно делать отдельный URL для каждого запроса (метода / функции), в GraphQL нужен только один URL для всех запросов.
За один запрос можно выбрать только те данные о сущностях, которые нужны. Сравнимо с SQL (тоже язык запросов), только это про API.
Язык запросов свой и не похож на другие API, а вот ответ обычно возвращается в формате JSON. Структура JSON строится на основе запроса.
Подробности далее, в обзоре теории по GraphQL (п. 2 - 6).
2. Структура URI в GraphQL
Клиент посылает запросы на один и тот же URL, а вся логика взаимодействия, включая выбор полей, фильтры и типы операций (запросы, мутации, подписка), управляется внутри запроса.
В сравнении с REST API:
GraphQL | REST AP | |
Определение | Один эндпоинт на все запросы. | Множество эндпоинтов, зависят от запроса и соответствуют конкретному ресурсу или действию. |
Пример 1. Получить данные о пользователе |
|
|
Пример 2. Получить данные о пользователе и его заказах |
|
|
Подробнее об отличиях в структуре URI
GraphQL - один эндпоинт на все запросы.
Клиент посылает запросы на один и тот же URL, а вся логика взаимодействия, включая выбор полей, фильтры и типы операций (запросы, мутации, подписка), управляется внутри запроса.
Пример:
Запрос на получение информации о пользователе:POST /graphql
Если надо получить информацию о пользователе и его заказах на один экран приложения, то можно сделать ОДИН запрос, в теле которого описать набор данных, которые необходимо вернуть.
REST API - множество эндпоинтов, зависят от запроса и соответствуют конкретному ресурсу или действию.
Структура URI заранее фиксирована и отражает иерархию ресурсов, а клиенту часто приходится делать несколько запросов для получения связанных данных.
Пример:
Запрос на получение информации о пользователе с id=1
:GET /users/1
Запрос на получение информации о заказах пользователя:GET /users/1/orders
Если надо получить информацию о пользователе и его заказах на один экран приложения, то нужно делать оба запроса - и на получение информации о пользователе, и на получение его списка заказов.
3. Тело запроса в GraphQL
3 ключевых принципа формирования Body запроса в GraphQL:
Запросы (Queries)
Мутации (Mutations)
Подписки (Subscriptions)
3.1. Запросы (Queries)
Запросы используются для получения данных. Клиент определяет, какие именно данные ему нужны, и получает их в виде JSON-объекта. В запросах можно использовать фильтры для более точного выбора данных.
Похоже на GET в REST API.
Пример - Просмотр списка записей на прием к врачу с фильтром по доктору
POST https://telmed.com/graphql
query {
appointments(doctorId: "doctor-456") {
id
date
time
patient {
id
name
}
doctor {
id
name
}
}
}
3.2. Мутации (Mutations)
Мутации используются для изменения данных на сервере, например, создания, обновления или удаления записей. Мутации похожи на запросы, но кроме получения данных, они изменяют их на сервере.
Похоже на POST, PUT, PATCH и DELETE в REST API.
Пример мутации - Запись на прием к врачу
POST https://test.com/graphql
mutation {
createAppointment(input: {
date: "2024-06-01",
time: "10:00",
patientId: "patient-123",
doctorId: "doctor-456"
}) {
appointment {
id
date
time
patient {
id
name
}
doctor {
id
name
}
}
}
}
Пример мутации - Изменение записи на прием к врачу
POST https://test.com/graphql
mutation {
updateAppointment(id: "appointment-789", input: {
date: "2024-06-02",
time: "14:00"
}) {
appointment {
id
date
time
patient {
id
name
}
doctor {
id
name
}
}
}
}
❗️ Обращаем внимание на название методов в мутациях - именно в них ответственность за создание и изменение данных: createAppointment и updateAppointment.
3.3 Подписка
Подписки позволяют клиенту получать данные в реальном времени при изменении состояния данных на сервере. Они полезны для таких сценариев, как обновления в реальном времени.
Для обмена данными используется протокол WebSocket.
Пример: у нас есть система чата, и мы хотим получать уведомления в реальном времени, когда кто-то отправляет новое сообщение в конкретном чате.
Запрос подписки будет выглядеть так:
POST https://test.com/graphql
subscription {
messageAdded(chatId: "1") {
id
content
sender {
name
}
timestamp
}
}
Пример ответа:
{
"data": {
"messageAdded": {
"id": "123",
"content": "Привет, коллеги! Классно, что вы дочитали до сюда :)",
"sender": {
"name": "Екатерина Ананьева"
},
"timestamp": "2024-10-23T10:20:00Z"
}
}
}
Как работает подписка:
Клиент отправляет запрос подписки.
Сервер "слушает" изменения, связанные с этой подпиской (например, когда появляется новое сообщение).
То есть сервер постоянно отслеживает определённые события или изменения в данных, которые могут происходить в системе.Когда происходит событие (например, добавление нового сообщения), сервер автоматически отправляет данные клиенту в реальном времени.
Подписки в GraphQL чаще всего используются для случаев, когда необходимо обновлять данные без явных запросов, таких как уведомления о новых сообщениях, изменениях статусов заказов, обновлениях цен в реальном времени и т.д.
Итого, в сравнении с REST API:
GraphQL | REST API | |
Синтаксис GraphQL (query, mutation, subscription). | Тело запроса зависит от HTTP-метода и передается в формате JSON. | |
Пример 1. Получить данные о пользователе |
Тело запроса (body):
|
Тело запроса (body): нет |
Пример 2. Создать данные о пользователе |
Тело запроса (body):
То, что мы хотим создать данные, определяет mutation в теле запроса. |
Тело запроса (body):
|
Подписка | Есть работа в реальном времени. | Отсутствует работа в реальном времени. |
Еще подробнее о сравнении тела запроса в GraphQL и REST API
GraphQL - синтаксис GraphQL (query, mutation, subscription).
Тело запроса содержит описание всех данных, которые клиент хочет получить или изменить, включая конкретные поля, фильтры и связанные ресурсы.
Это позволяет минимизировать объем передаваемых данных, запрашивая только те поля, которые необходимы.
Клиент точно указывает, какие данные ему нужны.
Язык запроса похож на JSON, но это не он.
Пример получения данных о пользователе:
POST /graphql
mutation { createUser(input: {name: "Екатерина Ананьева",
email: "info@getanalyst.ru",
phone: "123-456-7890"})
{
id
name
email
phone
}
}
Здесь клиент запрашивает только поля name
, id
и total
, и сервер возвращает ровно эти данные, что экономит трафик и ресурсы сервера.
Пример создания данных о пользователе:
POST /graphql
mutation { createUser(input: {name: "Екатерина Ананьева",
email: "info@getanalyst.ru",
phone: "123-456-7890"})
{
id
name
email
phone
}
}
В этом примере клиент отправляет мутацию createUser
с полями, которые нужно передать для создания нового пользователя: name
, email
и phone
.
То, что мы хотим создать данные, определяет mutation в теле запроса. |
REST API - тело запроса зависит от HTTP-метода и передается в формате JSON.
Тело запроса в REST обычно зависит от типа HTTP-запроса (GET, POST, PUT, DELETE) и передает данные в заранее определённой структуре, которая фиксируется на стороне сервера.
При этом сервер возвращает полный набор данных для конкретного ресурса, даже если клиенту нужны только некоторые поля.
Если в REST API методе есть тело сообщения, то оно передается в формате JSON.
Пример получения данных о пользователе:
GET /users/1
Нет тела запроса, игнорируется на уровне HTTP.
То, что мы хотим получать данные, определяет метод HTTP - GET.Пример создания данных о пользователе:
POST /users
{
"name": "Екатерина Ананьева",
"email": "info@getanalyst.ru",
"phone": "123-456-7890"
}
То, что мы хотим создать данные, определяет метод HTTP - POST и алгоритм, запрограммированный на сервере. |
4. Query-параметры запроса (или когда в GraphQL используют GET)
Query-параметры - параметры, передаваемые в URL после символа ?
.
В GraphQL query-параметры в URL обычно не используются. Запросы передаются в теле HTTP-запроса (чаще всего через POST), а вся логика — какие данные запрашивать и как их фильтровать — закладывается в сам запрос GraphQL.
В GraphQL query-параметры встроены прямо в тело запроса.
POST /graphql
Content-Type: application/json
{
"query": "query { user(id: \"1\") { name orders { id total } } }"
}
Тем не менее, запрос можно передать через URL в случае GET-запроса:
GET /graphql?query={user(id:"1"){name orders{id total}}}
Но это скорее исключение, чем нормальная практика.
В REST API query-параметры в URL обычно используются в GET запросах для фильтрации, сортировок и пагинации (постраничного получения) данных. В других запросах также допустимо использовать query-параметры.
5. Код ответа HTTP в GraphQL - cравнение с REST
В GraphQL коды HTTP не так сильно зависят от успеха или неудачи выполнения запроса. Даже если запрос завершился с ошибкой (например, пользователь не найден), сервер всё равно возвращает HTTP-код 200 OK, если сам запрос был успешно обработан (ошибки возвращаются внутри JSON-ответа).
Код 200 OK: Запрос выполнен успешно (даже если внутри ответа есть ошибка логики).
Коды 4xx или 5xx: Используются только для ошибок на уровне HTTP (например, сервер недоступен или неверный формат запроса).
В REST API коды HTTP играют большую роль для определения успешности или неуспешности выполнения запроса. В зависимости от операции и результата, возвращаются разные коды статуса:
200 OK: Запрос выполнен успешно, данные возвращены (например, GET-запрос).
201 Created: Новый ресурс был успешно создан (например, при POST-запросе для создания данных).
400 Bad Request: Неверный запрос (например, некорректные параметры).
404 Not Found: Ресурс не найден (например, пользователь с указанным ID не существует).
и т.д.
6. Тело ответа в GraphQL - cравнение с REST
В GraphQL тело ответа всегда возвращается в формате JSON и строго структурировано, где все данные содержатся внутри объекта data
. Если произошли ошибки, они передаются в объекте errors
. Ответ всегда стандартизирован, независимо от успеха или неуспеха запроса.
В REST API структура тела ответа зависит от конкретного запроса, а формат может быть различным (например, JSON, XML, HTML и т.д.). Ответ может содержать полный объект ресурса, частичные данные, или даже просто статус операции.
Вывод по теоретической части
GraphQL обладает рядом преимуществ по сравнению с REST API. Он предлагает гибкость в запросах, позволяя получать только те данные, которые необходимы, что сокращает избыточную передачу информации и повышает производительность.
Однако у GraphQL есть и недостатки — его сложнее внедрить в существующую архитектуру, а иногда излишняя гибкость может привести к перегрузке сервера сложными запросами.
Когда стоит использовать GraphQL? Он отлично подходит для проектов, где важно оптимизировать количество запросов и их объём, а также для систем с большим количеством взаимосвязанных данных. Однако в системах, где оптимизация в доли секунд не так важна, REST API остаётся более доступным и лёгким для реализации.
Подборка GraphQL API документации открытых систем
Здесь я собрала подборку сервисов с открытой GraphQL API-документацией, чтобы вы могли продолжить эксперименты после работы с этой статьей.
Эти примеры помогут на практике изучить, как GraphQL используется в разных областях, и как много странных API было создано для экспериментов.
GitHub GraphQL API — позволяет работать с репозиториями, пользователями, задачами и другими данными на GitHub.
Shopify GraphQL API — предоставляет возможность управлять интернет-магазинами, заказами и товарами в популярной платформе для онлайн-продаж в США.
Contentful GraphQL API — используется для интеграции с системой управления контентом, особенно для работы с постами и медиа в соцсетях.
SpaceX GraphQL API — позволяет запрашивать данные о запусках, ракетах, капсулах и других аспектах космических миссий.
Countries GraphQL API — используется для получения данных о странах, включая информацию о населении, языках и валюте.
SWAPI GraphQL API — используется для работы с данными о вселенной "Звёздных войн".
Большой справочник открытых GraphQL API на которых вы сможете практиковаться после прочтения этой статьи: подборка GraphQL API документации публичных сервисов
Заключение
Эта статья создана для практического обучения принципам работы GraphQL Будет полезна для IT-специалистов, работающих с интеграциями и в Backend-командах, где понимание современных API является ключевым навыком.
В ней есть всё: и практика, и подкрепляющая её теория. И, конечно же, сравнение с REST API. Именно благодаря глубокому пониманию REST гораздо легче осваивать другие "экзотические" API.
Рекомендую продолжить самостоятельное обучение: тестировать API-документацию из раздела рекомендаций.
Поздравляю вас с первыми шагами в работе с GraphQL! 🙂
Полезные ссылки
Пошаговый план: с чего начать изучение нового API? (статья в Telegram-канале)
Подробный обзор GraphQL API (+gRPC, серия статей в Telegram-канале)