Практическое введение в API GraphQL

GraphQL - это язык запросов для API. Но что именно это означает и как это работает? В самом простом случае GraphQL запрашивает определенные поля у объектов. В этой статье мы рассмотрим практический подход, чтобы быстро начать работу с GraphQL с помощью AppSync, DynamoDB и Postman. Давай начнем!

Предпосылки

  • AWS
  • Почтальон

Услуги

  • AppSync - это полностью управляемый сервис на AWS, который упрощает разработку API GraphQL.
  • DynamoDB - это быстрая и гибкая служба баз данных NoSQL на AWS.
  • Postman - это платформа для совместной работы по разработке API

AppSync

Первое, что мы сделаем, это настроим наш сервер GraphQL с помощью AWS AppSync. К счастью, это можно сделать быстро, поскольку у AWS есть образец шаблона, который мы можем использовать и который сделает за нас всю тяжелую работу. Чтобы начать с этого, перейдите в AWS AppSync и выполните следующие действия:

  1. [AppSync] Нажмите "Создать API".
  2. [Начало работы] Нажмите Создать с помощью мастера.
  3. [Создать модель] Нажмите "Создать".
  4. [Создать ресурсы] Нажмите "Создать".

Вот и все! Мы только что создали наш первый GraphQL API и DynamoDB, к которому он подключен. Следующее, что мы сделаем, - это запустим несколько запросов для записи и чтения из нашей таблицы. Вот изображение этих запросов:

Запросы

В пользовательском интерфейсе AppSync щелкните Запросы на левой панели, после чего откроется экран запроса. Здесь вы можете писать, проверять и тестировать запросы GraphQL. Здесь есть несколько разных панелей, поэтому давайте разделим их на три разных раздела для облегчения понимания. Вот изображение разделов:

  1. Первый раздел - это проводник запросов. Здесь вы можете выбрать, какие поля или атрибуты вы хотите использовать. Мутация в терминах GraphQL - это изменение данных или их запись в источник данных. Запрос в терминах GraphQL - это выборка данных или чтение из источника данных.
  2. Второй раздел - это предварительный просмотр проводника запросов. Попробуйте установить флажки в первом разделе: вы увидите, как предварительный просмотр обновляется вместе с вашим выбором. Это также то, что мы будем использовать в Postman.
  3. Последний раздел - это результат или ответ на ваш запрос.

Мутация

Нажмите кнопку воспроизведения ▶ ️, и откроется раскрывающийся список. Выберите createMyModelType, и в третьем разделе вы должны увидеть ответ, указывающий, что вы успешно вставили запись в DynamoDB. Вот изображение:

Попробуйте изменить переменную и снова нажмите кнопку воспроизведения, чтобы выбрать createMyModelType. В ответе вы должны увидеть новую переменную. Вот изображение:

Запрос

Большой! Теперь, когда мы сделали запись в наш источник данных, давайте попробуем прочитать из него, чтобы убедиться, что наши записи действительно там. Для этого вы должны снова нажать кнопку воспроизведения, но на этот раз выбрать из раскрывающегося списка listMyModelTypes, и вы должны увидеть ответ, показывающий только что созданные записи. Вот изображение:

Стоит отметить, что выбор из раскрывающегося списка воспроизведения фактически запускает запрос, показанный в разделе предварительного просмотра. Используйте все разделы вместе для разработки и тестирования запросов GraphQL.

DynamoDB

Давайте перейдем к DynamoDB, чтобы убедиться, что записи, которые мы создали в GraphQL, действительно существуют в нашей таблице. Выполните следующие пять шагов:

  1. Перейдите в DynamoDB
  2. Нажмите Таблицы на левой панели.
  3. Щелкните созданную вами таблицу
  4. Нажмите Элементы.
  5. Подтвердите, что записи есть

Почтальон

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

Более того, отправка запросов GraphQL в Postman не так интуитивно понятна, как может показаться. Поэтому я посвятил этот раздел рассмотрению конфигурации запроса, а также выполнения вызовов API с использованием Content-Type application / graphql и application / json .

Примечание. Для каждого запроса я включил сценарий CURL, который вы можете импортировать и / или ссылаться.

URL-адрес API и КЛЮЧ API

Чтобы получить конфигурации для вызова нашего сервера GraphQL, вернитесь на страницу настроек AWS AppSync. Отсюда мы возьмем URL-адрес API и КЛЮЧ API для использования в нашем запросе Postman. Вот изображение:

Конфигурация

Теперь, когда у нас есть URL-адрес API и КЛЮЧ API, пора настроить запрос в Postman. Для этого вернитесь в Postman и выполните следующие действия:

  1. Создать новый запрос
  2. Убедитесь, что выбран тип POST
  3. Введите URL-адрес API в URL-адрес запроса
  4. Введите x-api-key: {{API KEY}} на вкладке Заголовки.

Content-Type: приложение / graphql

Прочитать

Теперь мы собираемся сделать наш самый первый запрос GraphQL для получения данных с помощью Postman. Для этого мы собираемся добавить в наш заголовок Content-Type в качестве ключа и application / graphql в качестве значения.

Затем мы перейдем на вкладку Body и выберем GraphQL. Вот изображение:

Чтобы получить содержимое запроса, мы вернемся на страницу запросов AppSync и скопируем listMyModelTypes в разделе предварительного просмотра. Вот изображение для ссылки; код находится под ним:

query listMyModelTypes {
  listMyModelTypes {
    items {
      id
      title
    }
  }
}

Вернитесь в Postman, вставьте его в раздел «Запрос» на вкладке Body и нажмите «Отправить». Поможет следующее изображение:

Если вы все сделали правильно, то вы должны увидеть успешный ответ с элементами DynamoDb; этот ответ должен выглядеть так:

curl - location - запрос POST 'API_URL' \
- header 'x-api-key: API_KEY' \
- header 'Content-Type: application / graphql' \
- data-raw '{«Query»: «query listMyModelTypes {\ n listMyModelTypes {\ n items {\ n id \ n title \ n} \ n} \ n}», «переменные»: {}}'

Написать

Запись в базу данных через Postman аналогична чтению, но с некоторыми отличиями. Мы начнем с возврата на страницу запросов AppSync, чтобы скопировать createMyModelType в разделе предварительного просмотра. Вот изображение, которое поможет вам, и его код ниже:

mutation createMyModelType($createmymodeltypeinput: CreateMyModelTypeInput!) {
  createMyModelType(input: $createmymodeltypeinput) {
    title
    id
  }
}

Вернитесь в Postman, вставьте его в раздел «Запрос» на вкладке Body и нажмите «Отправить». Если вы выполнили описанные выше действия, вы должны увидеть успешный ответ с сообщением об ошибке. Вот изображение этого сообщения об ошибке:

Это потому, что нам не хватает переменных GraphQL. Чтобы получить синтаксис для этого, вернитесь на страницу запросов AppSync и скопируйте createmymodeltypeinput в переменные запроса раздела предварительного просмотра. На этом изображении показан процесс, и его код находится под ним:

{
  "createmymodeltypeinput": {
    "title": "Hello, Medium! - @songthamtung"
  }
}

Вернитесь в Postman, вставьте его в раздел «Переменные GraphQL» на вкладке Body и нажмите «Отправить». Это изображение поможет вам:

Если вы все сделали правильно, то вы должны увидеть успешный ответ с вновь созданным элементом из нашей переменной. Вот сообщение:

curl - location - запрос POST 'API_URL' \
- header 'x-api-key: API_KEY' \
- header 'Content-Type: application / graphql' \
- data-raw '{«Query»: «mutation createMyModelType ($ createmymodeltypeinput: CreateMyModelTypeInput!) {\ N createMyModelType (input: $ createmymodeltypeinput) {\ n title \ n id \ n} \ n}», «переменные»: {«createmymodeltypeinput»: {«Title»: «Привет, Medium! - @songthamtung (отправлено почтальоном) ”}}}’

Тип содержимого: приложение / json

Прочитать

Этот раздел предназначен для передачи данных JSON в теле вашего запроса. Он основан на конфигурации запроса, но использует Content-Type в качестве ключа и application / json в качестве значения на вкладке Заголовки.

Здесь важно отметить синтаксис, который показан ниже:

{
"query": "{listMyModelType{items{id,title}}}"
}

Мы в значительной степени взяли запрос из предыдущих разделов и собрали его в одну строку как значение для ключевого запроса. Вставьте его на вкладку Body в Postman, отметьте «raw» и выберите JSON в раскрывающемся списке.

Если вы все сделали правильно, то вы должны увидеть успешный ответ с элементами DynamoDb. Это будет выглядеть так:

curl - location - запрос POST 'API_URL' \
- header 'x-api-key: API_KEY' \
- header 'Content-Type: application / json' \
- data-raw '{
«запрос»: «{listMyModelTypes {items {id, title}}}»
} »

Написать

Запись в базу данных с использованием JSON аналогична чтению с использованием JSON в контексте сжатия полезной нагрузки в одну строку следующим образом:

{ "query": "mutation {createMyModelType(input:{title:\"JSON body\"}){title}}" }

Если вы все сделали правильно, вы должны увидеть успешный ответ с вновь созданным элементом из полезных данных JSON.

curl - location - запрос POST 'API_URL' \
- header 'x-api-key: API_KEY' \
- header 'Content-Type: application / json' \
- data-raw '{«Query»: «mutation {createMyModelType (input: {title: \" JSON body \ "}) {title}}»}'

Закрытие

Поздравляем, если вы зашли так далеко! Это непростая задача. Мы только что создали сервер GraphQL с помощью AWS AppSync, который читает / записывает в DynamoDB. Вдобавок к этому мы смогли выполнять вызовы API на сервер GraphQL с помощью Postman.

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

Мы сохраним их для будущих статей;).

Удачного кодирования!

Ресурсы