Using GraphQL directives

Learn about defining your GraphQL schema and leveraging directives.

A schema is defined in a GraphQL Schema Definition Language (SDL) file. The schema defines your GraphQL API and can incorporate directives, which are annotations that control how your schema is built and executed.

A directive is an identifier preceded by the @ character and optionally followed by a list of named arguments, which can appear after almost any form of syntax in the GraphQL query or schema languages. (To learn about GraphQL directives in general, see the GraphQL draft specification.)

Whether you specify your backends with the stepzen import CLI and let API Connect for GraphQL introspect the backend and generate your schema, or write your own schema code, or a combination of the two, you can take advantage of GraphQL directives that allow you to declaratively connect backends, assemble multiple schemas into one, write a set of queries in sequence, and more.

Specify schemas to include in your project using @sdl

Place one or more schema files (xxxx.graphql) in a directory in your API Connect for GraphQL project workspace.

Create an index.graphql file in the root of that directory, with the following structure. It specifies the relative paths for all the .graphql files you want to assemble into a unified GraphQL schema.

    schema @sdl(
      files: [
         # relative path to each file you want included
      ]
    ) {
        query: Query
    }

Here is an example of an index.graphql file that specifies two schemas:

schema @sdl(files: ["social.graphql", "weather.graphql"]) {
    query: Query
}

Custom directives

The @sdl directive is one of several constructs that help build your schema and control how it is executed at run time. For more information, see the Custom directives reference.