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 for GraphQL as a Service 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 for GraphQL as a Service 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, 
https://stepzen-chester.us-east.a.ibm.stepzen.net/examples/starwars/graphql

You can test the GraphQL API with API Connect for GraphQL Dashboard .

API Connect for GraphQL URLs always follow the same pattern:

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

You need your API Connect for GraphQL account and keys, a workspace, and your API endpoint URL. If you did not set up your machine already, complete the steps in Setting up your environment.

Authorization

API Connect for GraphQL as a Service supports two types of authorization:
  • Using access token

    To call the GraphQL endpoint using a Bearer token, you must first create an API key from the IBM SaaS console for the specific instance. For steps to create API keys, see Creating API keys.

    Use the API key in the following curl command to exchange it for an access token:

    curl --request POST \
  --url 'https://account-iam.platform.saas.ibm.com/api/2.0/services/<instance-id>/apikeys/token?includeBuiltinActions=true&includeCustomActions=true&includeRoles=true&prefixRolesWithDefinitionScope=true' \
  --header 'Content-Type: application/json' \
  --data '{
    "apikey": "<YOUR_API_KEY>"
  }'
    Sample response:
    {
  "token": "<Access_token>",
  "token_type": "Bearer",
  "expires_in": 7200,
  "expiration": 1759863889
}
    Request header format:
    {
  "Authorization": "Bearer <Access_token>"
}
  • Using the API Connect for GraphQL environment's API key directly

    Alternatively, you can use the API Connect for GraphQL environment's API key directly in the request header.

    Request header format
    {
  "Authorization": "apikey <MY_API_KEY>"
}

Query the API directly

Here’s a simple query you can run in the IBM API Connect for GraphQL Dashboard:

{
  allFilms {
    films {
      title
      director
      releaseDate
    }
  }
}

This will return a list of Star Wars films with their titles, directors, and release dates. For details about how to run the test, see Test a GraphQL API with API Connect for GraphQL Dashboard.

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

curl 'https://stepzen-chester.us-east.a.ibm.stepzen.net/examples/starwars/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"}'

When testing queries against API Connect for GraphQL as a Service 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