Delivery API

Pagination and drafts

Page through documents with limit and offset, and fetch drafts for previews.

The list queries, documents and documentsInCategory, return at most 100 documents at a time. Page through longer lists with limit and offset.

Limit and offset#

Arguments

limitInt: How many documents to return, from 1 to 100. Defaults to 100. Values outside the range are clamped.
offsetInt: How many documents to skip. Defaults to 0. Negative values count as 0.

Ordering#

Documents come newest first, by publishedAt. Categories come in alphabetical order by name and aren’t paginated: categories returns all of them.

Fetch every document#

Keep asking for the next page until one comes back shorter than the limit. This is how you’d build a sitemap or generate every page of a static site:

fetch-all-documents.js

const pageSize = 100

async function fetchAllDocuments() {
  const documents = []

  for (let offset = 0; ; offset += pageSize) {
    const response = await fetch('https://content.pmkin.io/graphql', {
      body: JSON.stringify({
        query: `query Documents($limit: Int, $offset: Int) {
          documents(limit: $limit, offset: $offset) { slug title publishedAt }
        }`,
        variables: { limit: pageSize, offset }
      }),
      headers: {
        Authorization: `Bearer ${process.env.PMKIN_API_KEY}`,
        'Content-Type': 'application/json'
      },
      method: 'POST',
      signal: AbortSignal.timeout(10_000)
    })

    if (!response.ok) {
      throw new Error(`PMKIN returned ${response.status}`)
    }

    const { data, errors } = await response.json()

    if (errors) {
      throw new Error(errors[0].message)
    }

    documents.push(...data.documents)

    // A short page is the last page.
    if (data.documents.length < pageSize) {
      return documents
    }
  }
}

Pages can shift

Offsets count from the newest document, so a document published while you page moves everything down by one, and you may see a document twice. Deduplicate by id or slug if that matters.

Drafts#

Lists normally hold only published documents. Pass includeDrafts: true to include drafts too, and use isPublished to tell them apart:

graphql

query Drafts {
  documents(includeDrafts: true, limit: 20) {
    title
    slug
    isPublished
  }
}

Drafts don’t have draft content

markdown and html are always the published version. For a document that was never published they’re empty, so includeDrafts is for listing what’s coming, not for previews. document and documentBySlug never return drafts.

Page size and complexity#

A list costs its limit times the fields you ask for, and html costs ten times as much as other fields. Ask for html only on the page that shows the document, and keep lists to titles, slugs and excerpts. See query complexity for the numbers.