Querying Posts

A guide to using the Mindful Query API to retrieve recently updated content posts.

Connecting to the API

For a high-level overview of GraphQL and connection information, review the API Details 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:

• A customer's organization, workspace, and view keys

If you're missing any of this information, please reach out to [email protected] for assistance.

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

https://graphql.mindfulcms.com/query

Creating a new workspace int he 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-namespace header to your client's configuration. In the GraphQL Playground, you can add that to the "HTTP Headers" tab:

Setting the namespace 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 the Query

The most commonly used query is the postInterfaceSearchConnectionquery, which returns a paginated list of content Posts with optional filter and sort criteria.

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

The postInterfaceSearchConnection query

The GraphQL query documentation for postInterfaceSearchConnectionand related input.

Parsing the Response

The GraphQL type returned from this query is the PostInterfaceSearchConnection. The PostInterfaceSearchConnection 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 2902. However, the default number of items returned from this query is only 10. In order to retrieve the remaining items, we must use cursor-based pagination.

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 value with the pagination.cursor input to retrieve the next page of results:

Second set of results using the previous query's endCursor.

Filtering the Response Data

The postInterfaceSearchConnection query supports a number of input arguments to filter the returned results:

Canonical Website

Posts can be filtered to only include results that are canonical to a specific website. To do that, include the Node ID of a website channel. The available website channels can be retrieved using the websiteChannelConnection query.

A set of results filtered by a canonical membership on a Website Channel.

To retrieve posts published to a specific Website Channel (regardless of canonical membership), use the websiteChannelPublishedPostEntries query.

Company

A query of Posts related to a Company Post

Display Type

Filtering results by a display type

Form Variant

Limit returned results to a specific variant form

Sorting

Sorting results by modification date, oldest first.

Status

Use the statusEdgeNodeIds field to filter Posts by their status.

Vocab Terms

Filtering results by a specific vocab term.

Website Channel Topics

Filtering results by a topic id. Use websiteChannelTopicInterfaceConnection to see available topics.

View

Using the view input to limit results to a certain customer view.

Post Fields

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

Type-specific fields

Some fields are specific to particular variant forms. A common example is the CompanyPost which has a number of different fields from the PostPost. To retrieve these fields, we'll use a GraphQL feature called an inline fragment — we're including the fields within the query directly, but only if the type of edge node is a CompanyPost.

Including the companyType field from the CompanyPost variant form.

Example Queries

Retrieving Posts modified in the last 24 hours

Query

query RecentlyModifiedPosts(
  $dates: PostInterfaceSearchDatesInput!,
  $pagination: PostInterfaceSearchPaginationInput!,
  $sort: PostInterfaceSearchSortInput!,
) {
  postInterfaceSearchConnection(
    dates: $dates,
    pagination: $pagination,
    sort: $sort,
  ) {
    pageInfo { hasNextPage endCursor }
    totalCount
    edges {
      _id
      node { ...RecentlyModifiedPostFieldsFragment }
    }
  }
}

fragment RecentlyModifiedPostFieldsFragment on PostInterface {
  _id
  _form { _id label }
  _meta { modified { date } }
}

To customize the fields returned, adjust the fragment:

fragment RecentlyModifiedPostFieldsFragment on PostInterface {
  _id
  _form { _id label }
  _meta { modified { date } }
  # combine channel hostname with integer id to make post short url
  canonicalWebsiteChannel { _id embeddedHostname { root } }
  integerId
  nameOrTitle { default }
  ... on CompanyPost {
    companyType
  }
  ... on PostPost {
    type { _id label }
  }
}

Arguments

Results

That's all for now! If you have any specific questions about using the Query 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.