ArticleConnection

The ArticleConnection type represents a paginated list of articles using cursor-based pagination. It provides a structured way to navigate through large sets of articles efficiently by dividing the data into manageable pages.

Connection Structure


{
  edges: [ArticleEdge!]!
  pageInfo: PageInfo!
}

edges: A list of ArticleEdge objects, each containing a single article (node) and a pagination cursor.
pageInfo: Contains metadata about the current page and pagination state.

Pagination Arguments

Argument	Type	Description
`first`	Int	Returns the first n elements from the list. Must be a positive integer.
`last`	Int	Returns the last n elements from the list. Must be a positive integer.
`after`	String	Returns elements after the specified cursor. Used for forward pagination.
`before`	String	Returns elements before the specified cursor. Used for backward pagination.

Constraints:

first and last cannot be used together in the same query.
When using after or before, the respective first or last argument must be provided to specify the page size.

PageInfo Structure


{
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

hasNextPage: Indicates if there are more items when paginating forward.
hasPreviousPage: Indicates if there are more items when paginating backward.
startCursor: The cursor corresponding to the first item in the current page.
endCursor: The cursor corresponding to the last item in the current page.

These fields help clients determine whether to show pagination controls and how to navigate between pages.

Usage Examples

Basic Pagination

Fetch the first 5 articles:


{
  articles(first: 5) {
    edges {
      node {
        id
        title
        publishedAt
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Forward Pagination

Fetch the next 5 articles after a given cursor:


{
  articles(first: 5, after: "YXJyYXljb25uZWN0aW9uOjQ=") {
    edges {
      node {
        id
        title
        publishedAt
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Backward Pagination

Fetch the previous 5 articles before a given cursor:


{
  articles(last: 5, before: "YXJyYXljb25uZWN0aW9uOjEw") {
    edges {
      node {
        id
        title
        publishedAt
      }
      cursor
    }
    pageInfo {
      hasPreviousPage
      startCursor
    }
  }
}

Navigate through pages using cursors:


{
  articles(first: 3) {
    edges {
      node {
        id
        title
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Use the endCursor from the above response to fetch the next page:


{
  articles(first: 3, after: "YXJyYXljb25uZWN0aW9uOjM=") {
    edges {
      node {
        id
        title
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Combined with Filtering

Fetch the first 5 articles published after January 1, 2023, sorted by published date descending:


{
  articles(first: 5, filter: { publishedAfter: "2023-01-01" }, sortKey: PUBLISHED_AT, reverse: true) {
    edges {
      node {
        id
        title
        publishedAt
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Edge Type

The ArticleEdge type represents a single edge in the ArticleConnection. It contains:


{
  node: Article
  cursor: String!
}

node: The Article object at the end of the edge. This field is optional and may be null if the article is unavailable.
cursor: A required string that acts as an opaque pagination token for this edge.

The edge connects the article data (node) with its pagination cursor (cursor), enabling efficient cursor-based pagination.

Pagination Best Practices

Use first with after for forward pagination and last with before for backward pagination to avoid ambiguous queries.
Always check pageInfo.hasNextPage and pageInfo.hasPreviousPage before attempting to fetch additional pages.
Limit the page size (first or last) to reasonable values (e.g., 10-50) to optimize performance and reduce payload size.
Use cursors returned in edges.cursor for reliable navigation instead of relying on offset-based pagination.
Combine pagination with filtering and sorting to fetch relevant subsets of data efficiently.

Performance Considerations

Cursor-based pagination is optimized for large datasets and avoids the pitfalls of offset-based pagination such as skipping or duplicating items.
Avoid requesting excessively large page sizes to reduce server load and response times.
Use filtering and sorting arguments to minimize the amount of data transferred and processed.
Cache cursors and pageInfo results on the client side when possible to reduce redundant network requests.

Article — The main object type representing an article.
PageInfo — Provides pagination metadata for connections.
ArticleEdge — Represents an edge in the ArticleConnection.

Notes

The API currently requires no authentication for querying articles; however, this may change in future versions.
Handle empty result sets gracefully by checking if edges is an empty array.
When a single page contains all available articles, pageInfo.hasNextPage and pageInfo.hasPreviousPage will both be false.
Implement proper error handling for invalid cursors or out-of-range pagination arguments.
Rate limiting may apply to paginated queries; design your client to handle rate limit errors and retry appropriately.