Creating a GraphQL schema

Write or generate a GraphQL schema that defines how to access data from a backend.

A GraphQL schema defines how a client can access data from a particular backend. The schema specifies the name of each type, a list of fields included in each type, and the scalar (data) type of each field.

There are two ways to create a GraphQL schema in API Connect for GraphQL:

Use the CLI stepzen import command to specify a backend data source so that API Connect for GraphQL can introspect it and generate a GraphQL schema automatically.
Use the GraphQL Schema Definition Language with one of the API Connect for GraphQL custom GraphQL directives to write a schema that connects to a backend and describes the data you want to access.

Generate a GraphQL schema with the CLI

You can generate a schemas using the stepzen import CLI command. This enables you to create a GraphQL schema for backend data sources including:

Any REST API, including REST interfaces on NoSQL databases:

stepzen import curl "YOUR_ENDPOINT" --header "Authentication: 123"

MySQL or PostgreSQL database:
```
stepzen import mysql | postgresql
```
Any GraphQL API, including schemas downloaded from the StepZen GraphQL Studio:
Draft comment: elizabeth_bowling@us.ibm.com
keep ref/link to Studio?
```
stepzen import graphql
```

When you run the stepzen import command, you are prompted to provide access information (such as a host name, headers, and so on.) for your data source. API Connect for GraphQL introspects the backend and generates the schema.

Write a schema with SDL and a custom directive

Create a .graphql file and use the GraphQL Schema Definition Language (SDL) plus one of the custom API Connect for GraphQL as a Service GraphQL directives to connect to a backend and describe the data you want to access. With a few lines of declarative code, you have a working schema.

The following custom directives are available:

@rest - Connect to REST APIs
@dbquery - Connect to SQL databases (MySQL, PostgreSQL)
@graphql - Connect to GraphQL APIs
@materializer - Advanced field resolution for complex data transformations

See the topics in the Connecting backends with custom directives section for details on how to extend a GraphQL API to connect to a variety of backends.

Draft comment: elizabeth_bowling@us.ibm.com
should we just call those "data sources" to shorten it in general usage?

Deploy your schema

After creating your GraphQL schema, deploy it to the server using the CLI:

stepzen deploy

Once deployed, you can test your API using the GraphiQL explorer, which is available both as a web interface and locally.