Using GraphQL

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 allows you to specify 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 structure it was requested, allowing the developer 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 allows you to gain 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 so that you can consume a StepZen API in your application.

Connecting to an API

A GraphQL API has a single endpoint for all of its data. Some GraphQL APIs are public and open. In these cases, you can begin querying 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 my account page. The folder name and endpoint name are specified by you when building and deploying your API.

Authorization

Many GraphQL APIs will require an API key for authorization to use the API. 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 passing your API key via an authorization header in the following format:

{
"Authorization": "apikey MY_API_KEY"
}

You can get your API key from your my account page.

Query the API Directly

For GraphQL APIs that have a browser-based query editor, you can build and test queries against them directly using this editor. For example, let's build a query for the Rick and Morty API/

You'll notice as you begin writing queries in the editor that it will offer code hints about the types and properties that you can query. Here's a simple query that you can try which will return an array of character names from the Rick and Morty show.

{
  character(id:1) {
    name
  }
}

This will return the following:

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

StepZen also provides the ability to query your APIs directly from the browser. In order to launch the query editor, you need build and deploy your schema using the stepzen start CLI command. For more details on using the CLI, check CLI commands documentation

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

You can test queries against StepZen APIs using CURL, however you will have to pass your API key in the Authorization header key. Here's an 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 my account page. The folder name and endpoint name are specified by you when building and deploying your API. The value of query should be something that matches your schema.

Query the API with Postman

Postman is a collaboration platform for API development. Select POST and include the endpoint. Select GraphQL and include the query.

Postman Request

Click Send to make the query.

Postman Response

This site uses cookies: By using this website, you consent to our use of cookies in accordance with our Website Terms of Use and Cookie Policy.