Легкое вступление в интеграцию GraphQL API

legkoe vstuplenie v integracziyu graphql api

GraphQL является прекрасной альтернативой REST (или другим дизайнам HTTP API). Это краткое вступление в основные концепции потребляющий API GraphQL.

Чтобы увидеть некоторые примеры использования GraphQL API:

Что такое GraphQL и какие проблемы он решает?

GraphQL – это «язык запросов для вашего API».

На простом английском языке это заставляет клиента определить, какие (вложенные) данные ему нужны.

Если мы сравним это с подходами REST:

  • «чистый» подход REST заключается в возвращении идентификаторов (или ссылок на ресурсы) для любых ассоциаций (или вложенных ресурсов).
  • Менее чистый подход – расширить все вложенные элементы.

Первая ситуация приводит к тому, что для получения всех данных нужно совершать много вызовов. Второе приводит к огромной полезной нагрузке и медленному времени загрузки.

В GraphQL клиент указывает в запросе, что он хочет расширить, переименовать или еще в ответе.

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

Схема

GraphiQL, «Интегрированная программа IDE для изучения GraphQL». доступный, перейдя к конечной точке в вашем браузере. Можно создать схему с помощью GraphQL CLI (нужно Node + npm 5+):

npx graphql-cli get-schema --endpoint $BASE_URL/api/graphql --no-all -o schema.graphql

Запросы

Концепция запросов GraphQL

Поля

То, что мы хотели бы получить в запросе, смотрите в документации GraphQL о «полах». Запрос GraphQL для этого возвращает поля name, fleeRate, maxCP, maxHPявляется следующим:

{
  pokemon(name: "Pikachu") {
    name
    fleeRate
    maxCP
    maxHP
  }
}

Аргументы

О том, как мы собираемся отфильтровать данные запроса, см. «аргументы» в документации GraphQL. Чтобы получить имена первых 10 покемонов, которые мы используем pokemons (first: 10) { FIELDS }чтобы увидеть выход здесь:

{
  pokemons (first: 10) {
    name
    fleeRate
    maxCP
    maxHP
  }
}

Псевдонимы

Псевдонимы дают нам возможность переименовывать поля. (См. документацию GraphQL по «псевдонимам»). На самом деле, мы собираемся использовать его для отображения полей в запросе, например. от верблюда до змеи:

{
  pokemon(name: "Pikachu") {
    evolution_requirements: evolutionRequirements {
      amount
      name
    }
  }
}

Выполнение этого запроса (здесь) дает нам следующее, где evolutionRequirements это то, к чему мы это призовем.

{
  "data": {
    "pokemon": {
      "evolution_requirements": {
        "amount": 50,
        "name": "Pikachu candies"
      }
    }
  }
}

Фрагменты

Определение расширяющихся полей полей. Это способ сохранить запросы DRY и в целом разделить повторяющиеся, повторно используемые или глубоко вложенные определения полей, фрагменты см. в разделе. в документации GraphQL. Это будет означать, что вместо того, чтобы делать (см. запрос в действии здесь):

{
  pokemon(name: "Pikachu") {
    weight {
      minimum
      maximum
    }
    height {
      minimum
      maximum
    }
  }
}

Например, мы можем запустить это (запрос здесь):

{
  pokemon(name: "Pikachu") {
    weight {...FullPokemonDimensions}
    height {...FullPokemonDimensions}
  }
}
fragment FullPokemonDimensions on PokemonDimension {
  minimum
  maximum
}

Выход эквивалентный:

{
  "data": {
    "pokemon": {
      "weight": {
        "minimum": "5.25kg",
        "maximum": "6.75kg"
      },
      "height": {
        "minimum": "0.35m",
        "maximum": "0.45m"
      }
    }
  }
}

Выполнение запроса GraphQL

Запрос GraphQL можно выполнить через POST или GET, он состоит из:

POST (рекомендовано)

  • Необходимые заголовки: Content-Type: application/json
  • Необходимый параметр тела JSON: query: { # insert your query }

Необработанный запрос HTTP

POST / HTTP/1.1
Host: graphql-pokemon.now.sh
Content-Type: application/json
{
        "query": "{ pokemons(first: 10) { name } }"
}

cURL

curl -X POST \
   \
  -H 'Content-Type: application/json' \
  -d '{
        "query": "{ pokemons(first: 10) { name } }"
    }'

ПОЛУЧИТЬ

  • Необходимый параметр запроса: query

необработанный запрос HTTP

GET /?query={%20pokemons(first:%2010)%20{%20name%20}%20} HTTP/1.1
Host: graphql-pokemon.now.sh

cURL

curl -X GET '?query={%20pokemons%28first:%2010%29%20{%20name%20}%20}'

Запросы верхнего уровня

На данный момент у GraphQL Pokemon API есть 2 типа запросов:

  • Первый покемон X: получить все предметы (с любыми полями, указанными в запросе)
  • Отдельный покемон по имени: получить один предмет по его скользку (с любыми полями, определенными в запросе)
  • Отдельный покемон по идентификатору: получите один предмет по слепому (с любыми полями, определенными в запросе)

Первый X Покемон

Запросы формы (посмотрите его в действии в GraphiQL):

{
  pokemons(first: 5) {
    name
    # other fields
  }
}

Одинокий покемон по имени

Запросы формы (посмотрите его в действии в GraphiQL):

{
  pokemon(name: "Pikachu") {
    name
    classification
    # other fields
  }
}

Обратите внимание на двойные кавычки ("") вокруг значения аргумента

Одиночный покемон по идентификатору

Запросы формы (посмотрите его в действии в GraphiQL):

{
  pokemon(id: "UG9rZW1vbjowMjU=") {
    name
    classification
    # other fields
  }
}

Обратите внимание на двойные кавычки ("") вокруг значения аргумента

Образцы запросов

Получите несколько покемонов, чтобы создать классификацию сильных/слабых/сопротивление

Запрос (посмотрите его в GraphiQL):

{
  pokemons(first: 100) {
    name
    image
    maxHP
    types
    weaknesses
    resistant
  }
}

Расширьте покемоны и эволюции для физической статистики и атак

Запрос (посмотрите его в GraphiQL):

{
  pokemon(name: "Pikachu") {
    ...PokemonWithAttack
    ...FullPhysicalStats
    evolutions {
      ...FullPhysicalStats
      ...PokemonWithAttack
    }
  }
}
fragment PokemonWithAttack on Pokemon {
  name
  attacks {
    fast {
      name
      type
      damage
    }
    special {
      name
      type
      damage
    }
  }
}
fragment FullPhysicalStats on Pokemon {
  height { ...FullDimension }
  weight { ...FullDimension }
}
fragment FullDimension on PokemonDimension {
  minimum
  maximum
}

Получите избранных покемонов как именуемые поля с именами их эволюции

Запрос (см. его в GraphiQL).

Мы можем переименовать запросы верхнего уровня с помощью псевдонимов. Это полезно, если мы хотим сделать следующее:

{
  pikachu: pokemon(name: "Pikachu") {
    ...FullPokemon
    evolutions {
      ...FullPokemon
    }
  }
  bulbasaur:pokemon(name: "Bulbasaur") {
    ...FullPokemon
    evolutions {
      ...FullPokemon
    }
  }
}
fragment FullPokemon on Pokemon {
  name
}

Если вы хотите узнать, как интегрироваться с GraphQL API:

— В Python смотрите пример клиентских запросов Python GraphQL с помощью gql
— В браузере JavaScript и Node смотрите информационный бюллетень Code with Hugo за прошедшую неделю

Читайте больше моих статей на моем веб-сайте Code With Hugo.

Добавить комментарий

Ваш адрес email не будет опубликован.