> ## Documentation Index
> Fetch the complete documentation index at: https://docs.validio.io/llms.txt
> Use this file to discover all available pages before exploring further.

# GraphQL Basics

> Learn GraphQL basics for the Validio API, including the schema, types, queries, mutations, and how to batch requests.

The [Validio API](https://docs.validio.io/developer/validio-api.md) is powered by GraphQL, a query language for APIs that gives you a flexible way to create custom queries and responses. Here are some basic GraphQL concepts that are good to know to get started.

> [!NOTE]
>
> If you're new to GraphQL, a good starting point is the official [Introduction to GraphQL](https://graphql.org/learn/).

## Schema

One of the core features of GraphQL is that the API is defined by a schema. The schema describes the types, interfaces, implementations, and attributes, and which operations are available. It's a great way to see what input and output the API expects. The [Queries](https://docs.validio.io/api-reference/graphql/queries/sourcesList.md), [Mutations](https://docs.validio.io/api-reference/graphql/mutations/sourceCreate.md), and [Types](https://docs.validio.io/api-reference/graphql/types/Source.md) sections of the [API Reference](https://docs.validio.io/api-reference.md) are generated from the Validio schema.

## Objects and types

Each operation (query, mutation, or subscription) can consist of one or more objects, used to construct the request and the response as you want. An object describes types and their attributes.

A type has a name that describes what it is and, optionally, fields and the types of those fields. If a type ends with an exclamation mark (`!`), the field is required and is always present.

```graphql title="GraphQL" theme={null}
type Hobby {
  name: String!
  timesPerWeek: Int
}

type Person {
  name: String!
  age: Int!
  phone: String
  hobbies: [Hobby!]
}
```

### Operations

When you interact with a GraphQL API, you use operations to describe your request: queries, mutations, or subscriptions.

* Queries are used to fetch data.
* Mutations are used to create, delete, or update data.
* Subscriptions are used to stream data from the server over a long-lived request, similar to gRPC streams or websockets.

> [!NOTE]
>
> The operations are fields on special root types, `Query` and `Mutation`. These root types describe the entry point of every request.

The following example shows how a query is defined. The `listPersons` query accepts an input of type `ListPersonsInput`, which carries a payload to the server, and the server responds with a list of persons. The list type ends with an exclamation mark, so there is always a list and never `null`.

```graphql title="GraphQL" theme={null}
input ListPersonsInput {
  hasAtLeastOneHobby: Boolean!
}

type Query {
  listPersons(input: ListPersonsInput!): [Person!]!
}
```

### Interfaces

An interface describes characteristics of an object that can be shared across multiple types. Interfaces are used when a resource can have multiple variants, just like objects in object-oriented programming. For example, an `Animal` interface can describe the attributes shared across animals, while each animal has its own implementation with attributes specific to it.

```graphql title="GraphQL" theme={null}
interface Animal {
  name: String!
  age: Int!
}

type Cat implements Animal {
  name: String!
  age: Int!
  legs: Int!
}

type Fish implements Animal {
  name: String!
  age: Int!
  fins: Int!
}

type Query {
  listAnimals: [Animal!]
}
```

When you query for animals and want specific data, you specify which fields to select for each implementation:

```graphql title="GraphQL" theme={null}
query ListAnimals {
  listAnimals {
    name
    age
    ... on Cat {
      legs
    }
    ... on Fish {
      fins
    }
  }
}
```

### Fragments

You will sometimes see fragments used in this documentation. Fragments are reusable building blocks that help you build complex queries by inlining the definitions. For more information about fragments, see the [GraphQL documentation](https://graphql.org/learn/queries/#fragments).

In the following example, a fragment on `Person` is reused for all fields that return a `Person`:

```graphql title="GraphQL" theme={null}
fragment PersonDetails on Person {
  name
  age
}

query GetPerson($id: PersonId!) {
  person(id: $id) {
    siblings {
      ... PersonDetails
    }
    parents {
      ... PersonDetails
    }
    friends {
      ... PersonDetails
    }
  }
}
```

## Caveats

If you're new to GraphQL, there are some things that are good to know beyond what it is and how it's designed, especially if you come from a RESTful background. These are common things that new users run into.

### Field names must be unique

When you spread specific implementations of an interface (that is, when an operation can return multiple types) and they share a field name, you must use an alias on one of them so that all field names are unique. To create an alias, write a name followed by a colon before the field you're selecting:

```graphql title="GraphQL" theme={null}
query MyQuery {
  listResource {
    id
    ... on TypeOne {
      typeOneValue: value
      width
    }
    ... on TypeTwo {
      typeTwoValue: value
      height
    }
  }
}
```

### Requests can be batched

In GraphQL, you don't need to send each operation separately: you can batch multiple operations and have them all executed in the same request. When you read data, the queries even run in parallel to speed up the request. Mutations, however, are always executed in sequential order.

For an example of a single mutation that changes several fields of a resource at once, see the [Update a validator](https://docs.validio.io/developer/validio-sdk/sdk-recipes/update-a-validator.md) recipe.