Loopwise Admin API Mutations

Overview

The Loopwise Admin API provides a variety of mutation operations to modify data in your school. These mutations enable you to create, update, and delete resources programmatically, giving you powerful automation capabilities.

Available Resources

The API provides mutations for the following resources:

• Courses — Create, update, and delete courses
• Posts — Create, update, and delete posts
• Assignments — Create and grade assignments
• Events — Manage calendar events
• Subscriptions — Manage membership subscriptions
• Send Custom Email — Send custom emails to users

Common Patterns

Error Handling

All mutations return an errors field that contains any validation or processing errors:

mutation {
  createCourse(input: { name: "" }) {
    errors {
      field
      message
    }
    course {
      id
      name
    }
  }
}

Response:

{
  "data": {
    "createCourse": {
      "errors": [
        {
          "field": "name",
          "message": "Name cannot be empty"
        }
      ],
      "course": null
    }
  }
}

Input Objects

Most mutations accept a single input parameter containing all required fields:

mutation {
  createCourse(input: {
    name: "Introduction to GraphQL"
    description: "Learn the basics of GraphQL"
    startDate: "2023-06-01"
  }) {
    course {
      id
      name
    }
    errors {
      field
      message
    }
  }
}

Basic Example

Here's a simple example of creating a new course:

mutation {
  createCourse(input: {
    name: "GraphQL Fundamentals"
    description: "Learn how to use GraphQL APIs"
    published: true
  }) {
    course {
      id
      name
      description
    }
    errors {
      field
      message
    }
  }
}

Authentication

All mutation operations require authentication with an API key. See the Authentication section for details on how to authenticate your requests.

Input Types

Most mutations in the Loopwise 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
    }
  }
}

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.

Input Validation

The Loopwise Admin API implements comprehensive input validation for all mutation operations. This validation ensures data integrity and provides clear feedback when input requirements aren't met.

Validation Process

When you submit a mutation, the API performs the following validation steps:

1. Type Checking: Ensures all input values match their expected types
2. Required Fields: Verifies all required fields are present
3. Format Validation: Validates that fields match expected formats (e.g., email addresses, dates)
4. Business Logic: Applies business rules specific to the resource (e.g., enrollment capacity limits)

Error Response Format

All mutations return an errors field that contains validation issues. Each error includes:

Example Error Response

{
  "data": {
    "createCourse": {
      "errors": [
        {
          "field": "name",
          "message": "Name cannot be empty"
        },
        {
          "field": "startDate",
          "message": "Start date must be in the future"
        }
      ],
      "course": null
    }
  }
}

Common Validation Rules

The following validation rules are commonly applied across mutations:

String Fields

• Required strings: Cannot be empty or contain only whitespace
• Length limits: Most string fields have maximum lengths (typically 255 characters)
• Format validation: Fields like emails, URLs, and phone numbers must match expected formats

Numeric Fields

• Range validation: Values must be within specified minimums and maximums
• Precision limits: Decimal values have precision constraints

Date Fields

• Format: Dates must be in ISO 8601 format (e.g., "2023-06-01T00:00:00Z")
• Range checks: Certain dates must be in the future or past depending on context

Relationships

• Existence: Referenced resources (by ID) must exist
• Permission checks: You must have access to the referenced resources

Handling Validation Errors

When developing with the API, we recommend:

1. Check for errors before assuming success — Always check the errors array before processing results
2. Display user-friendly messages — The error messages are designed to be helpful to end-users
3. Implement client-side validation — Implement similar rules in your client to provide immediate feedback

During development, you can intentionally submit invalid data to understand the API's validation requirements. This can be a helpful way to explore the API's expectations without consulting documentation for every field.