GraphQL - Introduction

• AWS North America (AWS NA): https://graphql.contentstack.com/
• AWS Europe (AWS EU): https://eu-graphql.contentstack.com/
• AWS Australia (AWS AU): https://au-graphql.contentstack.com/
• Azure North America (Azure NA): https://azure-na-graphql.contentstack.com/
• Azure Europe (Azure EU): https://azure-eu-graphql.contentstack.com/
• GCP North America (GCP NA): https://gcp-na-graphql.contentstack.com/
• GCP Europe (GCP EU): https://gcp-eu-graphql.contentstack.com/

The GraphQL Content Delivery API offers live preview functionality, enabling users to view real-time previews of their content. To make use of this feature, use the following endpoints for different regions:

• US (North America, or NA): https://graphql-preview.contentstack.com/
• Europe (EU): https://eu-graphql-preview.contentstack.com/
• Azure North America (Azure NA): https://azure-na-graphql-preview.contentstack.com/
• Azure Europe (Azure EU): https://azure-eu-graphql-preview.contentstack.com/
• GCP North America (GCP NA): https://gcp-na-graphql-preview.contentstack.com/
• GCP Europe (GCP EU): https://gcp-eu-graphql-preview.contentstack.com/
• AWS Australia (AWS AU): https://au-api.contentstack.com/

Additional ResourceYou can refer to our documentation on Live Preview for more information.

GraphQL Content Delivery API is a more efficient alternative to the Content Delivery APIs. It lets you fetch customized responses or retrieve data of nested or multiple resources through a single API request.

GraphQL is a flexible, customizable API query language. Contentstack’s GraphQL API gives you the power to query for exactly what you need and nothing more, for instance, you can even fetch data from multiple content types via a single API request. You can customize your responses by defining the structure of your requests. Currently, Contentstack GraphQL supports only queries and each requested resource’s GraphQL types are generated in real time, so your content remains current.

NoteContentstack's GraphQL API does not support mutations and subscriptions.

WarningAvoid using _regex or _exists in field UIDs. These are reserved keywords in GraphQL and may cause errors during queries. Use alternative naming to ensure smooth query execution.

If you are familiar with GraphQL, and want to get a hands-on experience of the API, here’s a quick link to our sample stack:

Query our sample stack

GraphQL API requests must be authenticated using the following details:

• Stack API key
• Environment
  
• Delivery token of the concerned environment

You need to pass the stack API Key in the URL and the publishing environment as a query parameter. Use the value of the delivery token against the access_token key in the header to authenticate your API request.

NoteTo fetch entries of a specific branch in your stack, you can pass the branch header while running the API request. This is an optional header that accepts the branch unique ID as value. You can also pass the alias ID as value for the branch header while querying the GraphQL API. If the branch header is not passed, then the API fetches details from the main branch by default.

The API Key is a unique key assigned to each stack. The delivery token is a read-only token, meaning this token can be used to fetch published content only, and not to edit or create new content in your stack.

Rate limiting defines the maximum number of API requests your organization can make within a specific time frame.

Request Types

• CDN Requests: Contentstack’s CDN serves cached responses. These requests are not subject to rate limiting.

• Origin Server Requests: Requests that are not cached and are routed to the origin server are subject to rate limits.

Default Limits

By default, origin server requests are limited to 80 requests per second per organization. All requests made from the GraphQL API endpoint counts towards this rate limit. The exact rate limit depends on your plan. If required, you can request an increase by contacting support.

NoteWhile CDN requests are not rate-limited, all API requests (CDN and origin) count toward your organization’s overall API usage quota. 

Rate Limit Exceeded

If your application exceeds the allowed rate limit within a given time period, the API will return an HTTP 429 (Too Many Requests) response.

Monitoring Rate Limits

You can track your current rate limit status using the HTTP response headers returned with each API request. These limits reset at the beginning of each time window.

Let’s look at the basic parts of a simple GraphQL query.

Click to enlarge

• Operation Type: GraphQL queries use the query keyword to indicate the type of operation we are performing.
• Arguments: An argument consists of a parameter-value set that can be used to specify arguments such as locale, skip, limit, where (conditions), etc.
• Fields: You can define the set of data for which you are asking.

The above query would look as follows when written in the form of a request:

https://graphql.contentstack.com/stacks/blt95a0a7afb9613f51?environment=production&query={all_product(where: {title: Galaxy Note}) { items { title description } } }

Within this API request, we state the stack API key and the publishing environment, followed by your query. The delivery token is passed as value of the access_token key in the header.

NoteTo fetch entries of a specific branch in your stack, you can pass the branch ID as value of the optional branch key in the header.

• The Contentstack GraphQL Content Delivery API is available at the following endpoints:
  • North America: https://graphql.contentstack.com/stacks/{stack_api_key}?environment={environment_name}
  • Europe: https://eu-graphql.contentstack.com/stacks/{stack_api_key}?environment={environment_name}
  • Azure North America: https://azure-na-graphql.contentstack.com/stacks/{stack_api_key}?environment={environment_name}
  • Azure Europe: https://azure-eu-graphql.contentstack.com/stacks/{stack_api_key}?environment={environment_name}
  • GCP NA: https://gcp-na-graphql.contentstack.com/stacks/{stack_api_key}?environment={environment_name}
  • Dedicated Infrastructure (DI): https://{DI}.graphql.contentstack.com/{region}
• To fetch content from Contentstack, use the endpoint for the region where your organization data resides.
• Pass the delivery token of the concerned environment in the following header while making an API request:
  access_token: "{delivery_token}"
• Pass the unique ID of a branch to which a content type belongs against the following header to fetch branch-specific content:
  

  branch: "{branch_ID}"

  
  

  NoteThis is an optional header.

• The Contentstack GraphQL API endpoint for both entries and assets is the same. It can be used to fetch content (both entries and assets) across multiple content types.

Contentstack’s GraphQL Content Delivery API supports both GET and POST methods on the GraphQL endpoint.

Let us understand how these methods work.

For GET requests, you must pass an environment name and a query in the request URL. Optionally, you can also specify an operation name or variable.

URL: https://{{domain}}/stacks/{{api_key}}

Method: GET

Headers:

• access_token: {{env_delivery_token}}
• branch: {{branch_ID}} (optional)

Parameters:

• environment={{environment_name}} (mandatory)
• query={{...}} (mandatory)
• variables={ "myVariable": "someValue", ... } (optional)
• operationName={{...}} (optional)

Here’s a sample cURL for a GraphQL GET request:

curl -g \
-X GET \
-H "Content-Type: application/json" \
-H "access_token: {{env_delivery_token}}" \
-H "branch: {{branchName || branchAlias}}" \
'https://graphql.contentstack.com/stacks/{{api_key}}?environment={{environment_name}}&query=query($locale:String){all_blog(locale:$locale){items{title}}}&variables={"locale":"en-us"}'

For POST requests, you must pass an environment name in the request URL, while the request body must include a query. Optionally, you can also specify an operation name or variable.

URL: https://{{domain}}/stacks/{{api_key}}

Method: POST

Headers:

• access_token: {{env_delivery_token}}
• branch: {{branch_ID}} (optional)

Parameters:

• environment={{environment_name}} (mandatory)

Body:

{
  "query": "...", # Mandatory
  "operationName": "...", # Optional
  "variables": { "myVariable": "someValue", ... } # Optional
}

Here’s a sample cURL for a GraphQL POST request:

curl -g \
-X POST \
-H "Content-Type: application/json" \
-H "access_token: {{environment_delivery_token}}" \
-H "branch: {{branchName || branchAlias}}" \
-d  '{"query":"query($locale: String){all_blog(locale: $locale){items{title}}}","variables":{{"locale":"en-us"}}}' \
https://graphql.contentstack.com/stacks/{{api_key}}?environment={{environment_name}}

Introspection system offers the ability to introspect what type of queries can run on the generated GraphQL schema. It provides a detailed description of the different object types that can be fetched from the schema.

For example, each content type in your stack has a corresponding GraphQL type and name. The introspection system would help you understand what fields can be queried, the arguments supported by those fields, and what output types can be returned by them.

We recommend that you structure your GraphQL queries by referring to the introspection schema. To explore the schema, you can run the following introspection query in Contentstack’s GraphiQL explorer:

query IntrospectionQuery {
  __schema {
    queryType {
      name
    }
    mutationType {
      name
    }
    subscriptionType {
      name
    }
    types {
      ...FullType
    }
    directives {
      name
      description
      locations
      args {
        ...InputValue
      }
    }
  }
}

fragment FullType on __Type {
  kind
  name
  description
  fields(includeDeprecated: true) {
    name
    description
    args {
      ...InputValue
    }
    type {
      ...TypeRef
    }
    isDeprecated
    deprecationReason
  }
  inputFields {
    ...InputValue
  }
  interfaces {
    ...TypeRef
  }
  enumValues(includeDeprecated: true) {
    name
    description
    isDeprecated
    deprecationReason
  }
  possibleTypes {
    ...TypeRef
  }
}

fragment InputValue on __InputValue {
  name
  description
  type {
    ...TypeRef
  }
  defaultValue
}

fragment TypeRef on __Type {
  kind
  name
  ofType {
    kind
    name
    ofType {
      kind
      name
      ofType {
        kind
        name
        ofType {
          kind
          name
          ofType {
            kind
            name
            ofType {
              kind
              name
              ofType {
                kind
                name
              }
            }
          }
        }
      }
    }
  }
}

You can also paginate the response schema returned by the Introspection system by passing the skip and limit parameters in the query. By default, the content types in the schema are sorted based on title_ASC and cannot be modified.

NoteThe 'SysAsset' GraphQL type will not be available in the paginated Introspection queries.

To skip certain content types when retrieving content, you can make use of the skip_content_type_uids=[] query parameter. You need to pass an array of content type UIDs to this parameter. This parameter comes really handy when you encounter a SCHEMA_BUILD_ERROR during introspection queries. Using it, you can skip the content type(s) causing the schema build error and view the rest of your stack data.

Contentstack’s GraphiQL explorer allows you to explore the GraphQL Content Delivery API. You can structure your GraphQL queries based on the available schema and test them out.

The GraphiQL explorer provides information about the content types and fields that are part of the schema.

Click to enlarge

You can also enter your own stack details and the required parameters in the GraphQL Explorer to try out the API.

Contentstack offers you a Postman Collection that helps you try out our GraphQL Content Delivery API. You can download this collection, connect to your Contentstack account, and try out the GraphQL API with ease.

Learn more about how to get started with using the Postman Collection for Contenstack GraphQL Content Delivery API.