Retrieving published content

A guide to using the `allPublishedContent` query to retrieve content via the BaseCMS GraphQL API

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.

You'll need the following information to read data from the API:

• An API URL

• A Tenant Key

• An active Base user with permission to read data

If you're missing any of this information, please reach out to [email protected] and we'd be happy to provide it!

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:

Creating a new workspace in the GraphQL Playground client

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:

Setting the tenant key header and a basic "ping" query.

Now that you've configured your API client, you can use a feature of GraphQL called introspection. Introspection allows you to browse the schema from your client, without access to the underlying codebase. To browse the schema, you can use the "Schema" (Raw output) or "Docs" (searchable, with comments) tabs on the right side of the screen.

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:

The basic `allPublishedContent` query

The GraphQL query documentation for `allPublishedContent` and related input.

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.

The limit input can only be used up to a maximum of 200 results. Due to a limitation of the underlying technology, using a limit+skip strategy will be unable to retrieve all results. If querying for more than 200 pieces of content, we highly recommend using 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).

Using a `limit` to return more than the default number of results.

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.

A query returning cursor pagination details.

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

Page 2 retrieved using the previous query's cursor.

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.

Most timestamp conversions will not add millisecond precision to a timestamp. If your timestamp is only using second precision, add 3 0's to the end of the timestamp:

1604206812 => 1604206812000

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

Querying for published content using the `after` and `since` inputs.

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.

A GraphQL query using `relatedContent` to show related companies and output type specific fields.

That's all for now! If you have any specific questions about using the GraphQL API or have suggestions on how this guide can be improved, please let us know via [email protected].

Please feel free to leave feedback on this page and let us know what you think.