GraphQL basics

Learn the basics of GraphQL by exploring how to connect to, and query, a simple GraphQL API.

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.

  • Get 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 using a single GraphQL query.

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

API Connect Essentials 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 API Connect Essentials API in your application.

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.

API Connect Essentials API URLs always follow the same pattern:

https://[ACCOUNT].[DOMAIN]/[FOLDER_NAME]/[ENDPOINT_NAME]/__graphql

Your administrator can tell you the account and domain. 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 API Connect Essentials API requires your API key. You must pass it in via an Authorization header in the following format:

{
  "Authorization": "apikey MY_API_KEY"
}

Query the API directly

A 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"
    }
  }
}

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 with curl:

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

When testing queries against API Connect Essentials 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"}'

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