Pagination in Teachify Admin API

Note: The Teachify Admin API is currently under development and not yet available for public use. This documentation is provided for preview purposes only.

Understanding Pagination

The Teachify Admin API uses page-based pagination for its collection queries. You request a page number with a fixed page size, and the response includes the items for that page along with metadata describing the overall result set.

Both input arguments (page, perPage) and response fields (nodesCount, currentPage, etc.) use camelCase in the GraphQL schema. The Ruby source uses snake_case (per_page, nodes_count); GraphQL converts automatically.

Pagination Structure

All paginated responses follow this shape:

{
  "data": {
    "resourceName": {
      "nodes": [
        // Array of resource objects for the current page
      ],
      "currentPage": 1,
      "totalPages": 8,
      "nodesCount": 150,
      "hasNextPage": true,
      "hasPreviousPage": false
    }
  }
}

Field	Type	Description
nodes	[Resource!]!	Items in the current page
currentPage	Int!	The 1-indexed page number returned
totalPages	Int!	Total number of pages for the result set
nodesCount	Int!	Total number of items across all pages (not just the current page)
hasNextPage	Boolean!	true if there is at least one more page after the current one
hasPreviousPage	Boolean!	true if currentPage > 1

Pagination Parameters

When querying paginated resources, pass these arguments:

Parameter	Type	Description
page	Int	1-indexed page number to retrieve. Defaults to 1. Values less than 1 are coerced to 1.
perPage	Int	Number of items per page. Defaults to 20. Maximum is 50 (values above are clamped).
limit	Int	Deprecated alias for perPage. Retained for backward compatibility. limit is only consulted when perPage is absent or less than 1; if perPage is a valid positive integer, limit is ignored entirely. When limit is used, values are clamped to 50 and values less than 1 fall back to the default.

Pagination Example

Initial Query

To fetch the first page of courses:

query {
  courses(page: 1, perPage: 10) {
    nodes {
      id
      name
      description
    }
    currentPage
    totalPages
    nodesCount
    hasNextPage
    hasPreviousPage
  }
}

Subsequent Pages

Increment page and reuse the same perPage:

query {
  courses(page: 2, perPage: 10) {
    nodes {
      id
      name
      description
    }
    currentPage
    hasNextPage
  }
}

Stop when hasNextPage is false, or when currentPage >= totalPages.

JavaScript Pagination Example

async function fetchAllCourses(apiKey) {
  const endpoint = 'https://teachify.io/admin/graphql';
  const perPage = 25;
  let page = 1;
  let hasNextPage = true;
  let allCourses = [];

  while (hasNextPage) {
    const query = `
      query Courses($page: Int!, $perPage: Int!) {
        courses(page: $page, perPage: $perPage) {
          nodes {
            id
            name
            description
          }
          currentPage
          totalPages
          hasNextPage
        }
      }
    `;

    const response = await fetch(endpoint, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Teachify-API-Key': apiKey
      },
      body: JSON.stringify({
        query,
        variables: { page, perPage }
      })
    });

    const result = await response.json();
    const data = result.data.courses;

    allCourses = [...allCourses, ...data.nodes];
    hasNextPage = data.hasNextPage;
    page += 1;

    console.log(`Fetched page ${data.currentPage}/${data.totalPages}. Total so far: ${allCourses.length}`);
  }

  return allCourses;
}

Best Practices

1. Use reasonable page sizes: Smaller sizes (10–25) suit interactive UIs; larger sizes (40–50) are more efficient for batch processing. The maximum perPage is 50.
2. Always check hasNextPage: Don’t assume more pages based on the number of items returned — the last page may still contain perPage items.
3. Sort is stable but implicit: Most collection queries sort newest-first by created_at. Don’t rely on a specific sort beyond what each query documents.
4. Handle empty results gracefully: If nodesCount is 0, nodes will be an empty array.
5. Avoid fetching all pages at once: For very large datasets, consider implementing user-driven “load more” or page navigation rather than auto-paginating in a tight loop.

Notes

• A small number of admin fields (currently courseCategories) use Relay-style cursor pagination instead of page-based. Those fields document first / after / pageInfo { hasNextPage, endCursor } directly on their resource page. The default for everything else is page-based as described above.