Retrieving published content

Connecting to the API

For a high-level overview of GraphQL and connection information, review the Getting Started section.

In this guide, we'll be using the GraphQL Playground client. You can feel free to use any API client but we think the GraphQL Playground has the best native autocompletion and schema visibility. Other commonly used clients are Insomnia, Altair, or Postman.

To get started, open the GraphQL Playground client and select New Workspace. Select the option to use a URL endpoint, and input your API URL:

Once you click open, your workspace will open up. Before you can make any queries against the API, you need to identify yourself. To do so, add the x-tenant-key header to your client's configuration. In the GraphQL Playground, you can add that to the "HTTP Headers" tab:

Making a Query

The most commonly used query in our GraphQL API is the allPublishedContent query. This query returns published content and provides a multitude of available inputs to limit, filter, and sort the results.

To start, lets enter the query and review the available inputs:

Parsing the response

The GraphQL type returned from this query is the ContentConnection. The ContentConnection has three properties: The total number of results available, the edge nodes (the content abstraction), and metadata about pagination.

In our query above, we see that the total number of items matching our query is 49. However, the default number of items returned from this query is only 10! In order to retrieve the remaining items, we have two choices: modify the pagination limit to return all results or use cursor pagination.

Limiting results

To adjust the query limit, include the pagination field along with your query input. The pagination field has two supported input modes: using a limit+skip or using a cursor hash (preferred).

Cursor Pagination

The other option is to use a feature called cursor pagination. When you make your query, a computed hash of all your input options is stored and used to compute your place within the set of results -- almost like a bookmark. To see the cursor for your query, include the pageInfo.endCursor field. Tip: pageInfo.hasNextPage can be used to determine if you've reached the end of the results.

You can then use the pageInfo.endCursor with the pagination.after input to retrieve the next page of results:

Filtering the response data

As mentioned above, the allPublishedContent query has many available inputs to modify the returned results. In this example we're going to use the since and after inputs to limit the results to items published within a certain date range. For more input options, feel free to browse the query schema in your client!

Date input format

All Date inputs in the GraphQL API expect to receive a Unix timestamp with millisecond precision. You can convert a date to a timestamp by using a utility such as Unixtimestamp.

The following query returns content published after Nov 1 2020 and before (since) Jan 1 2021:

Content fields

The edges.node items returned in the query are an abstraction around the Content type. For all available fields, see the schema documentation for the Content type -- we'll show a subset below.

Related Content

To return the documents specified in the related content field, use the relatedContent field on the Content type. This field supports many inputs (and the same pagination options as the allPublishedContent query), in this example we'll use includeContentTypes to limit the results to only related Company content items. We'll also use a GraphQL feature called aliasing to call this field companies in the result.

Type-specific fields

While most fields are common across all content types, some fields are specific to the individual type definition. In this example, we'll output the linkUrl and linkText fields, which are only present on the ContentPromotion type. To do this, we're using a GraphQL feature called an inline fragment -- we're including the fields within the query directly, but only if the ContentEdge node is a ContentPromotion.