Our Content Delivery GraphQL API Beta Version is Now Public

After several months of testing, Contentstack’s Content Delivery GraphQL API Beta version is now live and available for you to explore. We have also released a Postman collection for this API. 

Our Content Delivery GraphQL API Beta version now facilitates optimized schema handling, returns error debugging responses, uses database resources efficiently, and prevents malicious requests to the database. In other words, the API is now more stable, with better performance and improved security features.

Here’s a quick look at some of the significant changes that we have introduced since the alpha version:

• Paginate responses for referenced data and assets
• Query multiple content types in a single request
• Pass access tokens in the header of the API request instead of the URL
• Search using more flexible regular expressions
• Batch multiple API requests to the server
• Retrieve data for custom fields through GraphQL queries
• Traditional Reference field schema has been deprecated
• New and improved error response bodies
• Higher rate limit
• The release of a postman collection for our GraphQL API
  

Let’s dig a little deeper to understand the changes in detail.

Use Relay Specification to Paginate and Traverse Reference and Asset Field Data

Contentstack’s GraphQL API Beta now supports relay specification for Reference fields and assets. This means that you can paginate the list of referenced entries or assets returned in the response using the skip and limit parameters.

You can sort and filter the response data to request only for a specific list of nested references. This helps avoid overloading the database with unnecessarily large data requests.

Relay specifications take into account the data graph for an application. The data graph specifies the different connections that exist between each entity of the stack. This data graph consists of the following entities:

• Node: A node represents individual resources within the stack, for example, a particular content type (e.g., Product) or asset.
• Edges: Edges represent the contextual data that defines the connection between two content types, for instance, when a Product content type refers to the entries of another content type (e.g., Categories).
• Connection: Connection represents a standardized connection model to specify one-to-many relationships between a parent content type and its referenced child content types. You can paginate the referenced content returned in the response body using the skip and limit parameters.

Let’s look at an example to understand how relay specification works in Contentstack.

Consider a scenario where a few Blogs have references to related blog posts of the same content type or other related blog posts such as Sales Blogs and Marketing Blogs. Let’s say you want to fetch the value of the Title field of the basic blogs along with the values for the Title field of the Sales Blogs and Marketing Blogs.

{
  all_blogs {
    items {
      related_blogsConnection(
        limit: 5
      ) {
        totalCount
        edges {
          node {
            ... on Blogs {
              title
            }
            ... on SalesBlogs {
              title
            }
            ... on MarketingBlogs {
              title
            }
          }
        }
      }
    }
  }
}

If you want to view only the first five titles of the referenced blogs, you can use the limit parameter to paginate the list of referenced entries in the response body.

{
  all_blogs {
    items {
      related_blogsConnection(
        limit: 5
      ) {
        totalCount
        edges {
          node {
            ... on Blogs {
              title
            }
            ... on SalesBlogs {
              title
            }
            ... on MarketingBlogs {
              title
            }
          }
        }
      }
    }
  }
}

Note: You can only paginate response data for multi-content type referencing fields and single content type referencing fields that have been marked as “Multiple.”

Do Away with the Traditional Reference Field Schema

We have deprecated the traditional GraphQL query schema used to traverse through Reference fields. Now, you can use the relay specification logic to traverse through Reference field data.

However, one thing to keep in mind is that you can only paginate referenced entries for single content type referencing fields that have been marked as “Multiple” and multi-content type referencing fields in the response body.

The following table indicates the change in the schema of API requests that fetch Reference field data:

query {
  all_product {
    items {
      title
      home_appliances {
        ... on Electronics {
          title
          appliance_details
        }
        ... on KitchenAppliances {
          title
          kitchen_appliance_details
        }
      }
    }
  }
}

query {
  all_product {
    items {
      title
      home_appliancesConnection {
        edges {
          node {
            ... on Electronics {
              title
              appliance_details
            }
            ... on KitchenAppliances {
              title
              kitchen_appliance_details
            }
          }
        }
      }
    }
  }
}

Query Multiple Content Types in a Single Request

Contentstack’s Content Delivery GraphQL API Beta allows you to fetch the values of fields belonging to multiple content types in a single request. You can run a complex query to fetch data from multiple content types of the schema with a single request.

Consider a scenario in which you want to fetch all the values of the Title field of all Blogs and of Authors who have written a blog.

{
  all_blogs {
    items {
      related_blogsConnection {
        edges {
          node {
            ... on Blogs {
              title
            }
          }
        }
      }
    }
  }
  all_author_details {
    items {
      title
    }
  }
}

Regulated Rate Limiting to Shield the Origin Server

Contentstack's GraphQL API Beta now sets a maximum rate limit of 3 requests per second per organization for uncached GraphQL requests. Request-based rate limiting safeguards our origin server from malicious queries and provides a stable platform for any app that consumes our GraphQL API.

We do not set any rate limits on the GraphQL requests that fetch content from our CDN cache.

Retrieve Data Using More Flexible Regex Search

The Content Delivery GraphQL API Beta uses regular expression objects to define the search criteria for a query. The regex queries will now use the pattern parameter to filter out query results.

Here is how the syntax for regex searches has changed in Beta:

where: {
    field_uid_regex: "regex_value"
}

where: {
    field_uid_regex: {
      pattern: "regex_value"
    }
}

Note: The Contentstack GraphQL API currently does not support the use of regular expressions to filter query responses. The regex feature was available only in the beta release.

Paginate Documents Within Your Introspection Schema

Contentstack’s Content Delivery GraphQL Explorer only creates an introspection schema for the first 100 content types fetched from your stack. It was not possible to refer to content types other than the first 100 available. Querying content types that failed to load within the introspection schema resulted in breaking changes. This restriction no longer exists.

While fetching all the content types within your stack, you can provide arguments in the introspection query to paginate the introspection schema details.

For example, if you have more than 100 content types in your stack, you can get the rest of the batches’ items using the skip parameter in subsequent requests. To paginate the output of the request for introspection schema, you can use the limit parameter.

So, for instance, let’s say the Product Catalog stack contains more than 100 content types. To fetch content types other than the first 100 in batches, use the skip=100 and limit=4 query parameters to get only the first four content types other than the first 100: 

https://graphql.contentstack.com/stacks/blt20962a819b57e233?environment=production&skip=100&limit=4

Dataloaders to Batch GraphQL API Requests

Our Content Delivery GraphQL API Beta uses dataloaders to traverse the relationship between a Reference field and its referenced entries. Possessing the ability to accept an array of keys and return an array of values as requested, Dataloaders reduce the number of calls made to the database. This supersedes the basic resolver functions that instead make a host of calls to the database while traversing the referenced entries of a Reference field.

Consider a scenario where you need to fetch the values of the Title field of a Product and the title of the Category to which it belongs.

query {
  all_product(
    total
    items {
      title
      categoriesConnection {
        totalCount
        edges {
          node {
            title
          }
        }
      }
    }
  }
}

Here, a single product may be grouped under several categories, or a category can relate to several products. The resolver function that returns products cannot assume how many categories can be returned. This means that resolver functions will make several round trips to the database to fetch content.

The dataloader function instead batches multiple requests and makes a single call to the database for all the data related to products.

Fetch Data for Different Types of Custom Fields

Our Content Delivery GraphQL API Beta now allows you to retrieve data relayed by a custom field extension of a content type. Whether it may be a custom field of “boolean” data type or “JSON” data type, you can easily specify the “extension UID” to fetch field data.

Let’s consider a simple scenario to understand the query structure.

query {
  product {
    title
    product_description
  }
}

The response body of this query includes details of the “Product Description” custom field in JSON format.

Detect and Debug Errors On the Go

Contentstack now follows GraphQL’s error specifications while returning error messages for an API request that failed to execute.

Error responses now state the exact reason for failure, hints to detect the erroneous entity, and requests to debug the error.

Let’s look at an error message that is returned when an API request does not specify the publishing environment to better understand this improvement:

{
  code: 'MISSING_ENVIRONMENT',
  message: `The environment query parameter is required.`,
  details: {
    hint: "The url pattern should be '/stacks/{stack_api_key}?environment={env_name}'."
  }
}

Postman Collection for Our Content Delivery GraphQL API

We’re excited to announce Postman Collections for our Content Delivery GraphQL API. This collection lets you connect to your Contentstack account and try out our APIs using Postman’s native app. Click on the button below to get started.

Now that you know the benefits of our Content Delivery GraphQL Beta, check out our documentation to learn more about it and try out these new features.