# Что такое GraphQL?

**GraphQL** — это язык запросов к API и среда их выполнения, разработанный Facebook как альтернатива REST.

***

#### Особенности GraphQL

1. **Клиент сам выбирает данные**
   * В одном запросе можно указать, какие именно поля нужны.
   * Сервер вернёт только эти данные.
2. **Один эндпоинт**
   * В отличие от REST, где много URL (например, `/users`, `/users/1/orders`), в GraphQL всё идёт через один endpoint (обычно `/graphql`).
3. **Строгая типизация**
   * Данные описаны в виде схемы (Schema), где указаны типы объектов, их поля и доступные операции.
4. **Поддержка трёх типов операций**
   * **Query** — чтение данных (аналог GET).
   * **Mutation** — изменение данных (аналог POST/PUT/DELETE).
   * **Subscription** — подписка на обновления (реальное время, аналог WebSocket).

***

#### Преимущества

* Клиент получает ровно то, что нужно (нет «overfetching» и «underfetching»).
* Один запрос может объединять данные из разных источников.
* Поддержка работы в реальном времени через подписки.

***

#### Недостатки

* Сложнее в настройке, чем REST.
* Повышенная нагрузка на сервер (сложные запросы).
* Нужен контроль глубины запросов (иначе можно «уронить» сервер рекурсией).

***

#### Для QA важно

* Проверять корректность схемы (SDL).
* Тестировать разные типы операций: Query, Mutation, Subscription.
* Проверять обработку ошибок при запросе несуществующих полей.
* Тестировать перформанс при сложных вложенных запросах.

***

Пример запроса и ответа в **GraphQL**:

#### Запрос (Query)

Клиент хочет получить только имя и email пользователя с id = 1:

```graphql
query {
  user(id: 1) {
    name
    email
  }
}
```

***

#### Ответ сервера

Сервер вернёт **только те поля**, что были запрошены:

```json
{
  "data": {
    "user": {
      "name": "John Doe",
      "email": "john.doe@example.com"
    }
  }
}
```

***

#### Пример мутации (Mutation)

Добавим нового пользователя:

```graphql
mutation {
  createUser(name: "Alice", email: "alice@example.com") {
    id
    name
    email
  }
}
```

***

#### Ответ сервера

```json
{
  "data": {
    "createUser": {
      "id": "2",
      "name": "Alice",
      "email": "alice@example.com"
    }
  }
}
```

***

Таким образом, клиент управляет тем, **какие именно данные получить или изменить**, а сервер возвращает ровно этот набор.

#### Пример **Subscription** в GraphQL

**Задача:** клиент хочет получать в реальном времени новые сообщения в чате.

***

#### Запрос подписки (Subscription)

```graphql
subscription {
  newMessage {
    id
    text
    author {
      name
    }
  }
}
```

***

#### Как это работает

1. Клиент открывает подписку через WebSocket.
2. Каждый раз, когда на сервере появляется новое сообщение, сервер **сам отправляет** данные подписчикам.

***

#### Пример ответа сервера при новом сообщении

```json
{
  "data": {
    "newMessage": {
      "id": "101",
      "text": "Привет!",
      "author": {
        "name": "Alice"
      }
    }
  }
}
```

***

Таким образом, **Query и Mutation** работают как обычные запросы (клиент → сервер), а **Subscription** — это канал от сервера к клиенту для событий в реальном времени.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://kaze.gitbook.io/qa-theory/web/chto-takoe-graphql.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.