Tutorial: Create a GraphQL API for a GraphQL backend

Use the CLI command stepzen import graphql to create a GraphQL API for a GraphQL backend datasource.

This topic shows how to use the stepzen import mysql CLI command to introspect a GraphQL backend. The source code for the examples in this tutorial is stored in the Examples repository.

Tip: You can alternatively write your schema in a .graphql GraphQL Schema Definition Language (SDL) file, using the GraphQL directive @dbquery to connect to the GraphQL backend. See Connect a GraphQL backend for an example.

In this tutorial, example, you'll be connecting to the publicly available SpaceX Land API, hosted on GitHub.

Generate the GraphQL Schema

  1. Create a workspace directory for your project; for example:
    mkdir graphql-tutorial
  2. Navigate into your new workspace directory:
    cd graphql-tutorial
  3. Import the graphql template:
    stepzen import graphql

    The command starts creating a GraphQL API, and prompts you for information as shown in the following steps.

  4. Name your endpoint when prompted by the API Connect Essentials CLI. For this example, use the suggested endpoint directory (api) and name (vetoed-ferret):
    ? What would you like your endpoint to be called? api/vetoed-ferret

    The directory name is generated randomly. You can enter whatever folder/endpoint-name you prefer to customize it.

    After you choose your endpoint name, the command creates your directory and inserts a stepzen.config.json file. This JSON file contains the name of your endpoint.

    Created /Users/username/project-folder/stepzen.config.json
    Downloading from StepZen...... done
  5. The CLI then prompts you to provide some information needed to connect to your GraphQL endpoint:
    ? What is the GraphQL endpoint URL?  https://api.spacex.land/graphql
    ? Prefix to add to all generated type names (leave blank for none)
    ? Add an HTTP header, e.g. Header-Name: header value (leave blank for none)
    
    Generating schemas...... done
    Successfully imported schema schema_name from StepZen
    • ? What is the GraphQL endpoint URL?

      This is the endpoint you'll be connecting to; for this tutorial use the following the SpaceX Land API endpoint:

      https://api.spacex.land/graphql
    • ? Prefix to add to all generated type names (leave blank for none)

      A prefix can be prefixed to each of your GraphQL types; this is highly recommended because common type names (for example, Customer, or TimeZone) can cause confusion when multiple imported schemas have the same types. Choose a prefix that is unlikely to be used by another GraphQL endpoint in the same domain.

      For this tutorial, specify the following prefix: spacex_ so the types will be generated with names such as: spacex_Launch.

    • ? Add an HTTP header (Header-Name): header value (leave blank for none)

      Add authorization, if the API requires authorization. In this example, you don't need to enter API authorization because the SpaceX Land API does not require it. Leave this response blank.

    • ? Do you want to add an Authorization header?

      Respond with Yes to use an Authorization header, or No to skip it. If you choose to use the header, provide the header string in response to the next question.

    • ? What is your Authorization header?

      If you chose to use an Authorization header, input the header string provided by the API (if the API requires it). You don't need to add any prefix like apikey, just input the API key string itself.

Let's explore the schema code generated by the preceding steps. Open the directory to see the following files:

.
├── _graphql
│   └── api_spacex_land.graphql
├── index.graphql
└── stepzen.config.json
  • The graphql/api_spacex_land.graphql file contains a 1300+ line schema that maps out the types, mutations, and queries in the SpaceX Land API.

    This schema file enables you to call queries and mutations on the SpaceX Land API using API Connect Essentials, and even tie them into any of the other backends that API Connect Essentials integrates with.

    The best part is that you don't have to write it yourself!

    Here's an example of one of the types that was automatically generated:

    type spacex_CoreMission {
      name: String
      flight: Int
    }

    The type CoreMission has been prefixed with spacex_ as you specified earlier. This way, if you create another schema with a CoreMission type, there will be no type collision.

  • The index.graphql file tells API Connect Essentials how to assemble your schema from the various .graphql schema files in the project directory (in this example, you only have one, graphql/api_spacex_land.graphql).

    The index.graphql file looks like the following example:

    schema @sdl(files: ["graphql/api_spacex_land.graphql"]) {
      query: Query
    }

    If you have more than one schema file, it will appear in the files: [] brackets as part of a comma-separated list of strings.

  • At the bottom of the working directory is stepzen.config.json, which is used to configure the CLI.

  • The API in this tutorial doesn't require authorization, but if it did, you'd see an additional file in the directory, called config.yaml.

    The config.yaml file contains the following configuration information, which API Connect Essentials uses to connect to your backends:

    configurationset:
      - configuration:
          name: schema_name.graphql_config
          Authorization: { { API_KEY_HERE } }
    Note: The config.yaml contains authorization information, so make sure that it is included in your .gitignore before pushing to any Git branches.

Deploy and run your endpoint

Run the CLI command stepzen start to deploy the generated GraphQL schema to API Connect for GraphQL. A GraphQL API is immediately available on the endpoint URL.

  1. Execute stepzen start to deploy the generated GraphQL schema for your database to API Connect Essentials.

    A GraphQL API is instantly available on the endpoint you configured in the preceding section (...api/dozing-fly). You can query your GraphQL API from any application, browser, or IDE by providing the API key linked to your account.

  2. Now run the following query:
    query MyQuery {
      spacex_capsules {
        id
        reuse_count
        landings
      }
    }

    The result pulls data from the PostgreSQL database, and looks like the following example:

    {
      "data": {
        "spacex_capsules": [
          {
            "id": "C105",
            "landings": 1,
            "reuse_count": 0
          },
          {
            "id": "C101",
            "landings": 1,
            "reuse_count": 0
          },
          {
            "id": "C109",
            "landings": 0,
            "reuse_count": 0
          }, [...etc]

Now you can access the data from the SpaceX Land API on your own GraphQL endpoint. This enables you to integrate it along with data from other sources into a single consolidated API. For example, if you had weather data in a database, you could use the weather information for a specific date and connect it to the SpaceX Land API to get the weather for a specific launch.