Woolf API Overview

The Woolf API is a GraphQL-based interface that allows seamless integration with Woolf's Academic Management System (AMS). This reference guide provides detailed information on queries, mutations, schema structure, and how to interact with the API efficiently.

API Authorization

To access the API, you must authenticate using a College Token.

Retrieve your college token from the Configurations tab in College Settings on AMS.

Include the token as a Bearer Token in all API requests.


{
  "Authorization": "Bearer REPLACE_WITH_YOUR_COLLEGE_TOKEN"
}

GraphQL Schema Overview

The Woolf API follows the GraphQL specification, which is structured into different core elements.

API Schema


# === Queries ===

# Retrieves a list of activities based on filters
type Query {
  activities(
    courseId: String, 
    kinds: [ActivityKind!], 
    pagination: Pagination = {skip: 0, take: 100}, 
    resourceId: String, 
    resourceKinds: [ResourceKind!], 
    statuses: [ActivityStatus!], 
    studentId: String
  ): ActivityPaginationResult!

  # Retrieve a specific activity by ID
  activity(id: ID!): Activity!

  # Retrieve details of the authenticated college
  college: College!

  # Retrieve details of a specific course by ID
  course(id: ID!): Course!

  # Retrieve multiple courses with optional filters
  courses(
    degreeId: ID, 
    pagination: Pagination = {skip: 0, take: 200}, 
    statuses: [CourseStatus!]
  ): CoursePaginationResult!

  # Retrieve a specific resource by ID
  resource(id: String!): Resource!

  # Retrieve multiple resources
  resources(
    courseId: ID, 
    kinds: [ResourceKind!], 
    pagination: Pagination = {skip: 0, take: 200}, 
    statuses: [ResourceStatus!]
  ): ResourcePaginationResult!

  # Retrieve a student by ID
  student(id: String!): Student!

  # Retrieve a list of students with optional filters
  students(
    courseId: ID, 
    degreeId: ID, 
    pagination: Pagination = {skip: 0, take: 200}
  ): StudentPaginationResult!
}

# === Mutations ===

# API operations that modify data
type Mutation {
  addAttendance(attendance: AttendanceInput!): ActivityOutput!
  addFeedback(feedback: FeedbackInput!): ActivityOutput!
  addGrade(grade: GradeInput!): ActivityOutput!
  addResource(courseId: ID!, resource: ResourceCreateInput!): ResourceOutput!
  addStudentToCollege(email: String!, student: StudentInput): Student!
  addStudentToDegree(
    currency: Currency, 
    degreeId: ID!, 
    email: String!, 
    student: StudentInput, 
    tuitionCost: Int
  ): Student!
  addSubmission(submission: SubmissionInput!): ActivityOutput!
  archiveActivity(activityId: ID!): Boolean
  archiveCourseProgress(courseId: ID!, studentId: ID!): Boolean
  changeEmail(email: String!, id: ID!): Boolean!
  generateUserToken(id: String!): String!
  modifyResource(id: ID!, resource: ResourceModifyInput!): ResourceOutput!
}

# === Input Types ===

# Defines input for uploading assets (e.g., files, images)
input AssetInput {
  contentType: String
  fileName: String
  importUrl: String
}

# Used for recording student attendance in an activity
input AttendanceInput {
  studentId: String!     # ID of the student
  resourceId: String!    # ID of the resource
  timestamp: String      # Optional timestamp of attendance
}

# Used to submit feedback on an activity
input FeedbackInput {
  activityId: ID          # ID of the activity
  resourceId: String      # ID of the resource
  studentId: String!      # ID of the student submitting feedback
  teacherId: String       # ID of the teacher
  content: String         # Feedback content
  assets: [AssetInput!]   # Optional attached assets
  evidenceAssets: [AssetInput!]
}

# Used to assign a grade to an activity
input GradeInput {
  activityId: ID
  resourceId: String
  studentId: String!
  teacherId: String
  weightId: ID
  value: Float!            # Grade value
  assets: [AssetInput!]    # Attached supporting assets
  evidenceAssets: [AssetInput!]
}

# Defines the input format for creating a new resource
input ResourceCreateInput {
  name: String!           # Resource name
  kind: ResourceKind!     # Type of resource
  isGradeRequired: Boolean = true
  externalId: String
  content: String
  workload: Int
  weightIds: [ID!]
  assets: [AssetInput!]
  tags: [String!]
  teacherIds: [ID!]
}

# Defines input structure for modifying an existing resource
input ResourceModifyInput {
  name: String
  kind: ResourceKind
  isGradeRequired: Boolean
  externalId: String
  content: String
  workload: Int
  weightIds: [ID!]
  assets: [AssetInput!]
  tags: [String!]
  teacherIds: [ID!]
}

# Defines student input fields for API operations
input StudentInput {
  externalId: String
  nameFirst: String
  nameLast: String
}

# Used for submitting an assignment
input SubmissionInput {
  activityId: ID
  resourceId: String
  studentId: String
  content: String
  assets: [AssetInput!]
  evidenceAssets: [AssetInput!]
}

# === Enums ===

# Represents different types of activities
enum ActivityKind {
  addFeedback
  addGrade
  submitAssignment
  consumeResource
  attendMeeting
}

# Represents possible statuses of an activity
enum ActivityStatus {
  ACTIVE
  ARCHIVED
  PENDING
}

# Represents verification and operational statuses of a college
enum CollegeStatus {
  DRAFT
  VERIFIED
  REJECTED
  ARCHIVED
}

# Represents student status within a course
enum CourseStudentStatus {
  ACTIVE
  SUBMITTED
  PASSED
  FAILED
}

# Represents possible states of a course
enum CourseStatus {
  DRAFT
  REJECTED
  VERIFIED
  ARCHIVED
}

# Represents different types of resources
enum ResourceKind {
  ASSIGNMENT
  ASSIGNMENT_SUMMATIVE
  MEETING
  GENERAL
  PUBLICATION
  PUBLICATION_REVIEWED
}

# Represents the status of a resource
enum ResourceStatus {
  DRAFT
  REJECTED
  SUBMITTED
  VERIFIED
  ARCHIVED
}

# === Objects ===

# Represents an academic activity linked to a student and resource
type Activity {
  id: ID!
  created: DateTime!
  updated: DateTime!
  userId: ID!
  collegeId: ID!
  degreeId: ID
  weightId: ID
  courseId: ID
  resourceId: ID
  data: Json!
  kind: ActivityKind!
  status: ActivityStatus!
  resourceKind: ResourceKind
  grade: Float
  assets: [Asset!]!
  evidenceAssets: [Asset!]!
}

# Represents a course within a degree program
type Course {
  id: ID!
  updated: DateTime!
  created: DateTime!
  status: CourseStatus!
  rejectionReason: String
  name: String!
  descr: String!
  weights: [Weight!]!
  workloadRequired: Int!
  workload: Int!
}

# Represents a student enrolled in a college
type Student {
  id: ID!
  externalId: String
  name: String!
  email: String!
  updated: DateTime!
  created: DateTime!
  degrees: [DegreeStudent!]!
  courses: [CourseStudent!]!
}

# === Pagination Types ===

# Pagination result for retrieving activities
type ActivityPaginationResult {
  count: Int!
  list: [Activity]!
}

# Pagination result for retrieving courses
type CoursePaginationResult {
  count: Int!
  list: [Course]!
}

# Pagination result for retrieving resources
type ResourcePaginationResult {
  count: Int!
  list: [Resource]!
}

# Pagination result for retrieving students
type StudentPaginationResult {
  count: Int!
  list: [Student]!
}

Element	Description
Queries	Used to fetch data from the API, such as retrieving student records, course details, and activities.
Mutations	Used to modify data, such as adding students, updating grades, and submitting assignments.
Objects	Represents structured data returned by queries and mutations
Input Types	Defines structured objects used as inputs for mutations.
Enums	Defines a fixed set of values.
Scalars	Built-in primitive types.

Queries

Queries in GraphQL are allows fetching and retrieving data from the Woolf API. You can use them to:

Retrieve structured information (e.g., get student details, fetch course lists, check resource data).
Filter and refine results using parameters (e.g., filter students by course, fetch active resources only).
Request specific fields to optimize API responses and reduce data load.

Mutations

Mutations in GraphQL are used to modify or add data in the Woolf API.

Unlike queries, which retrieve data, mutations allow you to:

Create new records (e.g., enroll students, add resources, submit assignments).
Update existing records (e.g., modify student details, change emails, update grades).
Perform actions (e.g., submit feedback, archive progress, generate authentication tokens).

Best Practices for Using the Woolf API

Use the API Sandbox for Testing: Before deploying to production, test your API queries and mutations using the API Sandbox.
Secure API Authentication:
- Always include a valid Bearer Token in the Authorization header.
Optimize Queries for Performance:
- Request only the fields you need to avoid unnecessary data retrieval.
- Use pagination for queries returning large datasets.
- Apply filters to narrow down results and reduce response times.
Handle API Errors Gracefully: Check for common error codes and log errors for debugging and notify the Woolf of persistent failures.
- 401 Unauthorized – Invalid or missing API token.
- 403 Forbidden – Insufficient permissions.
- 400 Bad Request – Incorrect query structure or missing fields.

FAQs

How do I authenticate API requests?

All requests require a valid API token passed in the Authorization header.


{
  "Authorization": "Bearer YOUR_COLLEGE_TOKEN"
}

To obtain a token, refer to the authentication steps in the Getting Started for Developers.

How do I add a new student using the API?

Use the addStudentToCollege or addStudentToDegree mutations.

How do I handle API rate limits?

The Woolf API may have rate limits. If you encounter a 429 Too Many Requests error:

Reduce request frequency.
Implement exponential backoff for retries.

How do I get help with API integration?

For technical assistance, contact Woolf Support via support@woolf.education.