Input Types in Mutations

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

Understanding Input Types

Most mutations in the Teachify Admin API accept structured input objects that encapsulate all the data needed for the operation. These input types provide a consistent pattern for submitting data and help organize complex mutation parameters.

Input Type Structure

Input types follow these common patterns:

1. Named Input Objects: Most mutations accept a single parameter named input
2. Required vs Optional Fields: Fields are marked as required (!) or optional
3. Nested Objects: Complex operations may include nested input structures

Example Input Structure

Here’s an example of a typical mutation with an input type:

mutation {
  createCourse(input: {
    name: "Advanced GraphQL"
    description: "Deep dive into GraphQL concepts"
    startDate: "2023-07-01"
    endDate: "2023-09-30"
    categoryIds: ["cat_123", "cat_456"]
    lecturerIds: ["user_789"]
  }) {
    course {
      id
      name
    }
    errors {
      field
      message
    }
  }
}

Working with Input Types

Default Values

Some input fields have default values that are applied if the field is omitted:

type CreateCourseInput {
  name: String!
  description: String
  isPublished: Boolean = false  # Default is false if omitted
  maxStudents: Int = 100        # Default is 100 if omitted
}

Nullable Fields

Fields without the ! suffix are nullable and can be explicitly set to null:

mutation {
  updateCourse(input: {
    id: "course_123"
    description: null  # Explicitly clearing the description
  }) {
    course {
      id
      description
    }
  }
}

Nested Input Types

Some operations require nested input structures:

mutation {
  createCourse(input: {
    name: "Complete Web Development"
    sections: [
      {
        title: "HTML Basics"
        position: 1
        lectures: [
          { title: "Introduction to HTML", content: "..." },
          { title: "HTML Forms", content: "..." }
        ]
      },
      {
        title: "CSS Fundamentals"
        position: 2
        lectures: [
          { title: "Styling Basics", content: "..." }
        ]
      }
    ]
  }) {
    course {
      id
      name
    }
  }
}

Using Variables with Input Types

For client applications, using variables with input types is recommended to make code more maintainable:

mutation CreateCourse($input: CreateCourseInput!) {
  createCourse(input: $input) {
    course {
      id
      name
    }
    errors {
      field
      message
    }
  }
}

Variables:

{
  "input": {
    "name": "GraphQL Fundamentals",
    "description": "Learn the basics of GraphQL",
    "startDate": "2023-08-01"
  }
}

Input Type Reuse

Some input types are reused across multiple mutations:

• CourseInput might be used by both createCourse and updateCourse
• Common structures like AddressInput or DateRangeInput may be reused across many mutations

This consistency makes the API more predictable and easier to work with.

For specific input type definitions for each mutation, refer to the documentation for that specific resource type.