Что такое GraphQL? Комплексное введение для начинающих с примерами

Проще говоря, это похоже на то, когда вы идете в пиццерию и заказываете «приготовьте свою пиццу» - вы выбираете основу, соус, сыр, начинки, и когда пицца готова, вы получаете именно то, что вы попросил о.

В REST это похоже на выбор пиццы из предопределенных пунктов меню. Вы можете получить желаемую начинку, но вы также можете получить другие начинки (например, помидоры), о которых вы не просили, и иногда нам просто нужно вручную собрать из них помидоры.

С технической точки зрения GraphQL - это язык запросов - синтаксис для запроса данных из любого источника данных - будь то API или база данных. GraphQL является альтернативой REST API и предоставляет новый способ запроса данных. GraphQL позволяет указать, какие поля данных вам нужны, и предоставляет именно эти поля. Спецификация GraphQL определяет набор правил для реализации GraphQL API.

Важно отметить, что GraphQL не является языком запросов для вашей базы данных. В отличие от SQL, у вас нет запроса типа SELECT * from users для вашей базы данных. Вместо этого синтаксис GraphQL определяет, как запрашивать данные из вашего API. синтаксис запроса GraphQL выглядит так -

query getUsers{
    users {
        firstname
    }
}

Итак, QL в GraphQL означает язык запросов для вашего API, а не базу данных.

Стоит отметить, что GraphQL можно использовать с любым источником данных, например с REST API и базой данных. Он может быть подключен где угодно, построен на любом языке и может быть помещен поверх любой базы данных и технического стека, что означает, что вы можете использовать GraphQL поверх REST API и по-прежнему пользоваться преимуществами GraphQL без необходимости демонтировать существующий REST- на основе архитектуры. Вы можете использовать GraphQL в приложении Java, приложении JavaScript, Python, Django, Next.js.

GraphQL подходит как для клиентского, так и для серверного уровней. Вы создаете GraphQL API на стороне сервера, а затем используете этот GraphQL API на стороне клиента, запуская запросы GraphQL (запросы, мутации и т. Д.). Существуют такие инструменты, как Apollo, которые предоставляют полнофункциональные решения, помогающие создавать GraphQL API на сервере и использовать его на стороне клиента.

Пример REST vs GraphQL: создание запроса API

Допустим, мы хотим получить имя пользователя. В REST API у нас есть конечная точка, которую мы можем использовать для выполнения запроса GET. Конечная точка может выглядеть как /users/{id}/. Если мы используем запрос curl для выполнения вызова и передачи id пользователя, это будет выглядеть так:

curl \
-H "Content-Type: application/json" \
https://www.example.com/api/users/123`

Давайте посмотрим, как будет выглядеть запрос GraphQL -

Операция GET в REST выполняется Запросом в GraphQL.
У нас нет отдельной конечной точки для users в GraphQL. Каждый запрос отправляется в конечную точку /graphql.
Чтобы описать, какие данные нас интересуют, мы передаем соответствующие параметры в операцию «Запрос» и описываем, какой запрос нас интересует. API GraphQL может поддерживать что-то вроде запроса «getUsers», который является запросом, который мы можем использовать для получить пользователей.

Запрос curl к GraphQL API выглядит так:

curl \
-X POST \
-H "Content-Type: application/json" \
--data '{ "query": "{ user(id:123 ) { name } } " }' \
https://www.example.com/graphql

Попробуйте здесь образцы запросов GraphQL

REST vs GraphQL: реализация API

В мире REST у нас будут реализации ресурсов для каждой из наших операций, например, GET /user/{id} отображается в getUser(String id). getUser определяет, какие данные передаются при вызове этой конечной точки. Эта реализация ресурса также при необходимости вызовет любую последующую операцию - другие API или выборку непосредственно из базы данных.

В GraphQL при реализации GraphQL API нам нужно сначала определить схему API. Схема - это полное описание разрешенных запросов, изменений и параметров. Операция «GET» выполняется «Запросом» в GraphQL. Мы можем указать, какие аргументы принимает запрос в схеме.

type Query {
    getUser(id: $String!)
}

То, что мы возвращаем из этого getUser запроса, определяется функцией, называемой преобразователями. Решатели определяют, какие данные должны возвращаться при вызове поля. Каждый запрос отображается на преобразователь. Функция распознавателя может вызывать любой API или источники данных. Наш резолвер можно записать так -

getUser(args){
    const { id } = args;
    //fetch from database / API 
}

когда клиент получает getUser запрос, он получит такие данные:

{
    "data" : {
        "name": "Sample name"
    }
}

Терминология GraphQL

Запрос: запрос аналогичен GET в REST. Когда мы хотим получить информацию из GraphQL API, мы используем Query.
Мутация: мутация используется, когда мы хотим изменить данные на сервере. Мутация аналогична PUT, POST, DELETE, PATCH в REST API.
Схема: Схема - это полное представление о том, какие операции поддерживает GraphQL API.

Основные различия между REST и GraphQL

REST имеет несколько конечных точек. GraphQL имеет одну конечную точку - / graphql.
API-интерфейсы REST поддерживают PUT, GET, POST, DELETE, PATCH. GraphQL поддерживает запросы, мутации, подписку.
Конечные точки REST заполняются реализациями ресурсов. Поля GraphQL заполняются резолверами.
REST - коды состояния уровня 200, 400, 500. GraphQL - коды состояния 200 уровней.
Часто с REST для получения полных данных необходимо выполнить обходы. С помощью GraphQL вы можете получать несколько полей, поэтому получать все необходимые данные одним запросом.
Для REST форма данных определяется сервером. Для GraphQL форма данных определяется клиентом, вызывающим API.

Когда использовать GraphQL или REST

Когда использовать GraphQL

Когда у вас есть несколько нижестоящих API
Когда у вас есть посторонние данные, поступающие из нижележащих API
Когда вам важно, какие поля используются какими клиентами. С помощью GraphQL вы можете получить инструментарий на уровне поля.
Когда вы заботитесь о том, чтобы у всех клиентов была самая последняя версия вашего API. В GraphQL, поскольку существует одна конечная точка, все обновления предоставляются всем.
Если вы хотите создать API, ориентированный на пользовательский интерфейс.
Когда вы заботитесь о неполной или избыточной выборке.

Когда использовать REST

Когда вы сильно зависите от кеширования.
Если вы не знаете полного набора полей, вы можете получить их из последующих API. С GraphQL вам нужно знать схему заранее.
Когда вы сильно полагаетесь на коды состояния нижестоящих API. Все в GraphQL - это 200, поэтому вам нужно будет проанализировать объект ответа или объект ошибок.

Что необходимо для изучения GraphQL

Хотя я не думаю, что обязательно есть какие-либо предварительные требования, полезно знать следующее:

Основы разработки API
REST API
HTTP
Выбранный язык для реализации GraphQL API - JavaScript, Go, Java, Python и т. Д.

Ресурсы для изучения GraphQL

TL;DR

Проще говоря, GraphQL - это синтаксис для запроса данных. Большая разница между REST и GraphQL заключается в том, что существует только одна конечная точка - graphql, и помимо вызова конечной точки API и передачи желаемых параметров нам также необходимо точно указать, к каким полям мы хотим получить доступ.

С технической точки зрения GraphQL - это спецификация, обеспечивающая способ запроса данных. В спецификации указано, что должно происходить, когда данные запрашиваются и изменяются. GraphQL определяет способ запроса данных и предоставляет именно те данные, которые были запрошены. Поскольку это спецификация, API GraphQL могут быть созданы на языке - JavaScript, Java, Go, Python.

Другие ресурсы GraphQL, которые я опубликовал -

Получайте подобные статьи в свой почтовый ящик
Работайте со мной в режиме реального времени

Больше контента на plainenglish.io