# GraphQL

For a GraphQL API, Faustine turns every query and mutation of the schema into an operation with a fixed selection of fields. The schema comes from introspection of a running endpoint, from a file you upload or from the repository.

## Get started

Create the API from [**APIs**](https://auth.faustine.ai/go?to=%2Fintegrations%2Fapis) > **New API** with **GraphQL** as the **API type**. See [Create a GraphQL API](https://docs.faustine.ai/apis/create-a-graphql-api/).

## Where the schema comes from

The **Schema source** step of the wizard has three options.

| Option | What Faustine reads |
| --- | --- |
| **Fetch from connection** | Introspection of your live endpoint. You set up the first connection in the same step. This is the most reliable source. |
| **Upload SDL or introspection JSON** | A `.graphql` or `.gql` schema file, or the JSON result of an introspection query, up to 5 MB. |
| **Analyze the repository** | SDL files, a committed generated schema, or code-first definitions such as NestJS decorators, TypeGraphQL, Pothos or gqlgen. |

Every source is loaded into the same schema, and the operations are derived from it the same way. When a repository is connected, the analysis also reads the resolvers to write summaries and hints. Introspection and SDL win over code.

## Operations

Each root field of `Query` and `Mutation` becomes one operation. Subscriptions are not served.

The key is derived from the field name, with the same vocabulary REST operations use:

| Field | Key |
| --- | --- |
| `deals` | `deals.list` |
| `deal(id: ID!)` | `deals.get` |
| `createDeal` | `deals.create` |
| `updateDeal` | `deals.update` |
| `deleteDeal` | `deals.delete` |
| `searchDeals` | `deals.search` |
| `me` | `me.get` |

A mutation is a write. A mutation whose name starts with a destructive verb, such as `delete` or `remove`, is proposed as requiring confirmation.

### The selection of fields

An agent does not write GraphQL. Each operation has a selection of fields that the analysis fixes from the return type:

- The scalar and enum fields of the returned object, with `id`, `name` and `title` first.
- Related objects to a depth of 2.
- At most 60 fields.
- Fields that take required arguments are left out.
- A Relay connection is selected with its `edges`, `node` and `pageInfo`, and returned to the agent flat, as `items`, `pageInfo` and `totalCount` when the schema has it.

To get other fields in one call, the agent passes `$select`, a list of dotted field paths such as `["id", "owner.name"]`. It narrows or extends the selection within the operation's schema, to a depth of 3 and at most 120 fields.

## Connections

The **Base URL** of a GraphQL connection is the GraphQL endpoint itself, such as `https://api.nimbuscrm.example/graphql`. The gateway sends every query and mutation to it as a `POST` with the document and its variables.

When the response has `errors` and no data for the field, the call fails with the first error's message. When it has both, the agent receives the data together with the errors.

## Credentials

Credentials are sent as for a REST API: an HTTP header or a query parameter for a key, `Authorization: Bearer` for a token. See [Authentication](https://docs.faustine.ai/apis/authentication/).

## Testing

**Test connection** on a GraphQL connection introspects the endpoint and reports how many queries and mutations the credential sees. A schema built per user looks smaller to an anonymous or under-scoped credential, and that count is what the analysis will find. If introspection is turned off on the endpoint, upload the schema instead.

After the analysis, a connection is tested with a read operation, as for any API.

## Next steps

- [Create a GraphQL API](https://docs.faustine.ai/apis/create-a-graphql-api/): the steps of the wizard for each schema source.
- [Operations](https://docs.faustine.ai/apis/operations/): review the operations and their flags.
- [Add a connection](https://docs.faustine.ai/apis/add-a-connection/): add the endpoints of your other environments.
- [API frameworks](https://docs.faustine.ai/technologies/api-frameworks/): the frameworks the wizard lists for GraphQL.