Teachify Admin API Best Practices

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

This guide provides best practices for working with the Teachify Admin API to ensure optimal performance, security, and reliability.

Authentication

• Secure your API keys: Never expose your API keys in client-side code or public repositories.
• Use separate API keys for different environments (development, staging, production).
• Implement proper key rotation procedures for your organization.
• Monitor API key usage to detect unusual patterns that might indicate a security breach.

Request Optimization

Requesting Only What You Need

GraphQL allows you to specify exactly which fields you need. Always limit your queries to only the fields your application requires:

# Good: Only requesting needed fields
query {
  courses(first: 10) {
    nodes {
      id
      name
    }
  }
}

# Avoid: Requesting unnecessary fields
query {
  courses(first: 10) {
    nodes {
      id
      name
      description
      startDate
      endDate
      createdAt
      updatedAt
      # ... many more fields
    }
  }
}

Pagination

When working with collections, always use pagination to limit the amount of data returned:

• Use the first parameter to limit the number of items (default: 20, max: 100)
• Use the after parameter with the endCursor from previous responses to fetch subsequent pages
• Check hasNextPage to determine if more data is available

query {
  students(first: 50, after: "cursor-from-previous-page") {
    nodes {
      id
      name
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Filtering

Use filters to narrow down results on the server side rather than fetching large datasets and filtering client-side:

# Good: Server-side filtering
query {
  students(filter: { courseId: "course-123" }) {
    nodes {
      id
      name
    }
  }
}

# Avoid: Fetching all students and filtering client-side

Error Handling

• Always check for errors in the response before processing the data
• Implement proper error handling for different types of errors:
  • Authentication errors (invalid or expired API key)
  • Validation errors (invalid input)
  • Resource not found errors
  • Rate limiting errors

Example error handling in JavaScript:

async function makeApiRequest(query, variables) {
  const response = await fetch('https://teachify.io/admin/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Teachify-API-Key': apiKey
    },
    body: JSON.stringify({ query, variables })
  });

  const result = await response.json();

  // Check for GraphQL errors
  if (result.errors) {
    const error = result.errors[0];

    // Handle different error types
    if (error.message.includes('authentication')) {
      throw new Error('Authentication failed. Check your API key.');
    } else if (error.message.includes('rate limit')) {
      throw new Error('Rate limit exceeded. Please try again later.');
    } else {
      throw new Error(`API Error: ${error.message}`);
    }
  }

  // Check for mutation-specific errors
  if (result.data && result.data.someMutation && result.data.someMutation.errors) {
    const mutationErrors = result.data.someMutation.errors;
    throw new Error(`Mutation failed: ${mutationErrors[0].message}`);
  }

  return result.data;
}

Rate Limiting

The Teachify Admin API implements rate limiting to ensure fair usage. To avoid hitting rate limits:

• Cache responses when appropriate
• Implement exponential backoff for retries
• Batch operations when possible instead of making many small requests
• Spread out non-urgent requests over time

Webhooks vs. Polling

For real-time updates, consider using webhooks (when available) instead of polling the API:

• Webhooks provide immediate notifications when data changes
• Polling can lead to increased API usage and potential rate limiting
• If polling is necessary, use reasonable intervals (e.g., no more than once per minute for non-critical data)

Common Arguments

All queries and mutations require the subdomain argument to identify the school context:

query {
  courses(subdomain: "school-subdomain") {
    nodes {
      id
      name
    }
  }
}

Handling Large Operations

For operations that might affect many records:

• Use pagination to process large datasets in smaller batches
• Implement proper error handling and retry logic
• Consider using background jobs for very large operations
• Monitor the progress of long-running operations