GraphQL | Faustine Docs

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 > New API with GraphQL as the API type. See 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.

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: the steps of the wizard for each schema source.
Operations: review the operations and their flags.
Add a connection: add the endpoints of your other environments.
API frameworks: the frameworks the wizard lists for GraphQL.