Обзор GraphQL API

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

Все запросы API отправляются на следующий URL:

https://archie-core.services.archie.com/graphql

Чтобы направить запрос к вашему конкретному проекту, необходимо включить заголовок x-project-id, содержащий ID вашего проекта, в каждый HTTP-запрос.

Понимание полей

GraphQL — это спецификация для запроса полей объектов. Вот простой запрос Archie Core, который ищет конкретный город по его уникальному id и запрашивает возврат полей nameCity и state.

query MyQuery {
  citiesById(id: "e14638cb-6d72-4a36-b30f-9b763136a7bb") {
    id
    nameCity
    state
  }
}

И вот результат:

{
  "data": {
    "citiesById": {
      "id": "e14638cb-6d72-4a36-b30f-9b763136a7bb",
      "nameCity": "Chicago",
      "state": "Illinois"
    }
  }
}

Результат имеет ту же форму, что и запрос. Это ключ к GraphQL: вы всегда получаете то, что запрашиваете, и сервер знает, какие поля запрашивает клиент.

Запросы Archie Core GraphQL интерактивны и изначально поддерживают реляционные запросы. Это означает две важные вещи:

1. Запрос можно изменить в любое время.
2. Связанные данные можно объединять без написания сложных запросов к базе данных и сериализаторов.

Понимание аргументов

Мощь Archie Core GraphQL API дополнительно обогащается возможностью указывать различные аргументы при выполнении запроса. Это было продемонстрировано в примере выше, где конкретная строка UUID передаётся в качестве аргумента запросу (...citiesById(id: "e14638cb...")).

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

Например, поскольку таблица Cities имеет поле ID, установленное как уникальное (так как это первичный ключ), мы можем затем запросить конкретную запись City:

query MyQuery {
  citiesById(id: "e14638cb-6d72-4a36-b30f-9b763136a7bb") {
    id
    nameCity
    state
  }
}

Переменные

Вы можете сделать запросы многоразовыми и динамическими, используя переменные в API Explorer.

Для работы с переменными вам нужно:

1. Заменить статическое значение в запросе на $variableName.
2. Объявить $variableName как одну из переменных, принимаемых запросом.
3. Передать variableName: value в отдельном словаре переменных.

Вот запрос:

query MyQuery ($filter: StudentsFilter) {
  students(filter: $filter) {
    items {
      firstName
      email
    }
  }
}

Вот переменная:

{
  "filter": {
    "isActive": {
      "equals": true
    }
  }
}

И вот результат:

{
  "data": {
    "students": {
      "items": [
        {
          "firstName": "James",
          "email": "james.smith@example.com"
        },
        {
          "firstName": "John",
          "email": "john.williams@example.com"
        },
        {
          "firstName": "Mary",
          "email": "mary.brown@example.com"
        },
        {
          "firstName": "Mary",
          "email": "mary.johnson@example.com"
        },
        {
          "firstName": "Elizabeth",
          "email": "elizabeth.davis@example.com"
        }
      ]
    }
  }
}

Псевдонимы

Псевдонимы используются для возврата объектов с именами, отличными от имён их полей. Это необходимо при получении объектов одного типа с разными аргументами в одном запросе.

Ниже вы можете видеть, что первый город имеет псевдоним “cityOne”:

query MyQuery {
  cityOne: citiesById(id: "e14638cb-6d72-4a36-b30f-9b763136a7bb") {
    id
    nameCity
  }

  cityTwo: citiesById(id: "0174dc55-d494-4ebc-a0e9-13575461cad4") {
    id
    nameCity
  }
}

Результат:

{
  "data": {
    "cityOne": {
      "id": "e14638cb-6d72-4a36-b30f-9b763136a7bb",
      "nameCity": "Chicago"
    },
    "cityTwo": {
      "id": "0174dc55-d494-4ebc-a0e9-13575461cad4",
      "nameCity": "Miami"
    }
  }
}

Фрагменты

Запросы могут становиться длинными и сложными. Фрагменты создают набор полей, которые можно использовать для представления определённого набора. Если вам нужно несколько полей от двух разных авторов, вы можете использовать фрагмент вместо повторения полей дважды. В этом запросе у нас есть фрагмент с именем { ...studentFrag }:

query MyQuery {
  studentA: studentsById(id: "287cff0a-345b-4cca-9e9a-75a2161238fd") { ...studentFrag}

  studentB: studentsById(id: "97fb89ac-e0ad-44f5-b671-24a1b751287c") { ...studentFrag}
}

fragment studentFrag on Students {
      id
      firstName
      email
      isActive
      city {
        nameCity
        state
      }
    }

Результат:

{
  "data": {
    "studentA": {
      "id": "287cff0a-345b-4cca-9e9a-75a2161238fd",
      "firstName": "James",
      "email": "james.smith@example.com",
      "isActive": true,
      "city": {
        "nameCity": "Chicago",
        "state": "Illinois"
      }
    },
    "studentB": {
      "id": "97fb89ac-e0ad-44f5-b671-24a1b751287c",
      "firstName": "John",
      "email": "john.williams@example.com",
      "isActive": true,
      "city": {
        "nameCity": "Seattle",
        "state": "Washington"
      }