Announcing General Availability of Contentstack’s GraphQL Content Delivery API

It’s official. Contentstack’s GraphQL Content Delivery API is now available to all customers.

When we first added support for GraphQL about two years ago, we saw it as a natural addition to a developers’ arsenal. We knew that providing more stable support would unlock tremendous value for developers and provide an efficient way to query data, no matter what they plan to build.

In the last two years, we worked hard to achieve that. We brought significant improvements in terms of capability, stability, and performance. Having proven itself over many months with customers using it in production, we are moving our GraphQL Content Delivery API from limited availability to general availability. Additionally, this latest release offers further rate limit increases, better stability, the ability to query multiple content types in a single request, and more.

Before we dig into what has changed from our Limited Availability version, here are highlights of the capabilities of our GA GraphQL API:

• Rate limit of 80 requests per second per organization, in addition to the existing REST rate limit
• Query entries of up to three content types in a single request
• Paginate responses for referenced data and assets
• Use relay specification logic to traverse through Reference field data
• Retrieve data of different types of custom fields
• Paginate introspection schema details
• Use postman collection to test our GraphQL API

Now let’s look at some of the changes we have brought in this GA release from our Limited Availability version.

Higher Rate Limits

Our Limited Availability version had a rate limit of 3 requests per second per organization. We have increased the default limit to 80 requests per second per organization for uncached GraphQL requests to accommodate more production use cases. For requests that fetch content from our CDN cache, there is no rate limit.

Query More Content Types in a Single Request

You can now retrieve entries of up to three content types in a single GraphQL API request.

query {
  all_product {
total
    items {
      title
      }
  }
  all_category {
    total
    items {
      title
    }
  }
  all_brand {
    total
    items {
      title
    }
  }
}

Limits on Query Complexity and Cost

GraphQL gives developers the ability to make complex queries. While this is an advantage for the requester, it also opens up certain security risks. A malicious attacker can request a heavy, nested query that can overload the server or database. Or even legitimate users can inadvertently request data that may cause performance issues.

One of the best strategies to mitigate such risks is to set the following standards:

• A single GraphQL query can fetch a maximum of 7,500 records
• A single GraphQL query can fetch a maximum of 100 referenced records for a single Reference field connection
• You can use the skip and limit pagination parameters to fetch more reference connection records

We do a cost and complexity analysis before executing the query and restrict the query from being executed if it exceeds the set limits.

{
  all_blogs(limit:100) {
    items {
      related_blogsConnection(limit:75) {
        totalCount
        edges {
          node {
            ... on Blogs {
              title
            }
          }
        }
      }
    }
  }
}

Now, we calculate the total records (entries) the above query is trying to fetch:

Depth 0 (Blogs Content Type) = 100 blog entries

Depth 1 (Related Blogs Reference Field): 100 x 75 = 7,500 related blog entries

Total Blog Entries: 100 blog entries + 7,500 related blog entries = 7,600 entries

Since the total entry count exceeds the maximum allowed limit of 7,500, we can prevent this query from connecting to the database.

If you intend to fetch more data, we recommend you paginate the references effectively and make multiple requests.

Refer to our documentation to learn more about how we calculate query cost and complexity.

Breaking Changes to Keep in Mind

Contentstack will continue to support the GraphQL Content Delivery API Limited Availability version for 30 days post the GA release.

To facilitate a smooth transition to the newer version of the API, we have listed below a few breaking changes in the API that you need to update within your backend code. You can incorporate these changes before the duration (mentioned above) to avoid schema build errors.

Update to All Asset Related Typenames

Contentstack converts every field UID to its corresponding GraphQL typename that follows the Pascal naming convention. However, a few instances may involve two different fields or objects having the same typename. This occurrence is referred to as a Typename Collision.

In our endeavor to avoid typename collisions, we prefix all asset-related GraphQL typenames with “SysAsset” instead of “Asset.”

Here’s a list of all the system-defined fields that have changed:

• "Asset" to "SysAsset"
• "AssetWhere" to "SysAssetWhere"
• "AssetConnection" to "SysAssetConnection"
• "AssetEdge" to "SysAssetEdge"
• "AllAssets" to "AllSysAsset"
• "AssetSystemField" to "SysAssetSystemField"
• "AssetDimension" to "SysAssetDimension"
• "AssetDimensionWhere" to "SysAssetDimensionWhere"
• "AssetOrderBy" to "SysAssetOrderBy"
• "TransformUrl" to "SysAssetTransformUrl"
• "ImageFormats" to "SysAssetImageFormats"
• "DisableValues" to "SysAssetDisableValues"
• "FitValues" to "SysAssetFitValues"
• "OrientValues" to "SysAssetOrientValues"
• "OverlayAlignValues" to "SysAssetOverlayAlignValues"
• "OverlayRepeatValues" to "SysAssetOverlayRepeatValues"
• "AutoValues" to "SysAssetAutoValues"
• "DispositionValues" to "SysAssetDispositionValues"

Introduction of the X-Resolver-Cost Response Header

To prevent malicious queries from hitting our backend database, we now perform a static analysis of each query before it hits the database. The x-resolver-cost response header calculates the worst-case response size that can be fetched by the query and provides an apt query cost analysis. This response header returns the total number of database round trips made for a single GraphQL query.

Future Steps

Contentstack will continue to add more capabilities to our GraphQL Content Delivery API as we go forward. Check our Change Log section to see the complete list of changes. To get started with your GraphQL API, check out our developer documentation.