StepZen is now part of IBM. For the most recent product information and updates go to
https://www.ibm.com/products/stepzen

GraphQL Basics

The Basics of Querying GraphQL APIs

GraphQL is a query language for APIs that offers some major benefits over the alternatives such as:

  • Ask for and receive only what you need: A GraphQL query specifies only the data you need and the result returned by the query will only include the data requested.
  • Predictable results: The results from a GraphQL query will be returned in the same structure as the request, enabling you to quickly predict and code for those results.
  • Get multiple resources in a single request: GraphQL APIs have a single endpoint for all their data and multiple resources can be requested via a single GraphQL query.

You can learn more about the benefits of GraphQL at GraphQL.org.

StepZen provides all of the advantages of GraphQL for your applications without having to build and maintain your own GraphQL server. In this section, we'll explore how to use GraphQL to consume a StepZen API in your application.

The following subsections describe how to query and connect to an API:

Connect to an API

A GraphQL API has a single endpoint for all of its data. Some GraphQL APIs are public and open so you can query them directly. For example, the Rick and Morty API is available at https://rickandmortyapi.com/graphql.

Many GraphQL APIs, particularly public APIs, include a built-in query editor. For example, the Rick and Morty API includes a GraphQL Playground editor:

Rick and Morty GraphiQL

StepZen API URLs always follow the same pattern:

https://[ACCOUNT_NAME].stepzen.net/[FOLDER_NAME]/[ENDPOINT_NAME]/__graphql

Your account name can be found in your StepZen dashboard. The folder name and endpoint name are specified by you when building and deploying your API.

Authorization

Many GraphQL APIs require an API key for authorization. This is typically passed via an Authorization key in the header. For example, the GitHub GraphQL API requires that the user pass a GitHub personal access token in the header:

{
  "Authorization":"Bearer MY_TOKEN"
}

Every StepZen API requires your API key. You must pass it in via an Authorization header in the following format:

{
"Authorization": "apikey MY_API_KEY"
}

You can get your API key from your StepZen dashboard.

Query the API Directly

The browser-based query editor for GraphQL APIs enables you to build and test queries directly against the APIs. For example, let's build a query for the Rick and Morty API.

As you begin writing queries in the editor, it will offer code hints about the types and properties that you can query. Here's a simple query that returns an array of character names from the Rick and Morty show:

{
  character(id:1) {
    name
  }
}

The query returns the following:

{
  "data": {
    "character": {
      "name": "Rick Sanchez"
    }
  }
}

StepZen also enables you to query your APIs directly from the StepZen dashboard in the "Explorer" tab.

Query the API with curl

If you prefer, you can query and test a GraphQL API via the command line using curl. For example, here is the same query as above sent via curl:

curl \
-X POST \
-H "Content-Type: application/json" \
--data '{ "query":"{ character(id:1) { name } }" }' \
https://rickandmortyapi.com/graphql

When testing queries against StepZen APIs using curl, ensure you pass your API key in the Authorization header key. For example:

curl 'https://[ACCOUNT_NAME].stepzen.net/[FOLDER_NAME]/[ENDPOINT_NAME]/__graphql' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Apikey [MY_API_KEY]' --data-binary '{"query":"{\n customer (id: 1) {\n city\n email\n orders {\n createdOn\n customerId\n lineitems {\n id\n productId\n }\n }\n }\n}\n"}'

Your account name can be found in your StepZen dashboard. The folder name and endpoint name are specified by you when building and deploying your API. We strongly suggest that the value of query match your schema.

Query the API with Postman

Postman is a collaboration platform for API development.

Follow the steps below to invoke a query with Postman:

  1. Select POST and include the endpoint.

  2. Select GraphQL and include the query:

    Postman Request

  3. Click Send to invoke the query:

    Postman Response