Querying 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.

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

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:

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:

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.

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

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.

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

Company

Display Type

Form Variant

Sorting

Status

Vocab Terms

Website Channel Topics

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.

Example Queries

Retrieving Posts modified in the last 24 hours

Query

Arguments

Results

Copy

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:

Copy

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 }
  }
}

Limits documents returned to those modified after April 1 midnight (UTC) and before April 2.

Feel free to use any ISO-8601 date string here, if you'd prefer to query data against another timezone.

Copy

{
  "dates": [{
    "field": "META_MODIFIED_DATE",
    "after":  "2024-04-01T00:00:00Z",
    "before": "2024-04-02T00:00:00Z"
  }],
  "pagination": {
    "limit": 100,
    "cursor": {
      "direction": "AFTER"
    }
  },
  "sort": {
    "order": "ASC",
    "field": "META_MODIFIED_DATE"
  }
}