openapi: 3.1.0
info:
  title: Learning API
  version: v1
  description: |
    Demo Learning API used for educational purposes.
    This API is powered by a Remockly mock server and supports
    activities, quizzes, assignments, badges, and reporting.
  termsOfService: http://example.com/terms
servers:
  - url: http://example.com
    description: Demo server
security:
  - imfKey: []
tags:
  - name: Activities
    description: Manage learning activities such as lessons and exercises.
  - name: Quizzes
    description: Create and manage quizzes and quiz questions.
  - name: Badges
    description: Manage learner achievement badges.
  - name: Scores
    description: Retrieve learner scores.
  - name: Checklists
    description: Manage onboarding and learning checklists.
  - name: Assignments
    description: Assign learning content to users.
  - name: Reports
    description: Reporting endpoints.
  - name: Other
    description: Miscellaneous endpoints.
paths:
  /:
    get:
      tags:
        - Other
      summary: Get API information
      operationId: getApiInfo
      responses:
        '200':
          description: API info message.
          content:
            application/json:
              schema:
                type: string
              example: This is a demo API.
        '400':
          $ref: '#/components/responses/badRequest'
  /activities:
    post:
      tags:
        - Activities
      summary: Record activity
      operationId: postActivity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/activity'
            example:
              data:
                type: quiz
                name: Onboarding Part 1
                item: Sign agreements
                answer: a
              metadata:
                user: abc123
                domain: http://example.com
                path: /onboarding/start
                timestamp: '2023-02-19T09:31:27Z'
      responses:
        '204':
          description: Activity recorded successfully.
        '400':
          $ref: '#/components/responses/badRequest'
  /quizzes:
    post:
      tags:
        - Quizzes
      summary: Create quiz
      operationId: postQuiz
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/quiz'
              name: Who we are
              passingScore: 0.8
              questions:
                - type: null
                  question: What is our mission?
                  choices:
                    a: Multinational espionage agency
                    b: Prevent manmade catastrophes
                    c: Do amazing stunts
                  correctAnswer: b
      responses:
        '201':
          description: Quiz created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/quiz'
        '400':
          $ref: '#/components/responses/badRequest'
    get:
      tags:
        - Quizzes
      summary: Get quizzes
      operationId: getQuizzes
      responses:
        '200':
          description: List of quizzes.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/quiz'
              example:
                - id: quiz_abc987def123
                  name: Who we are
                  passingScore: 0.8
        '400':
          $ref: '#/components/responses/badRequest'
  /scores:
    get:
      tags:
        - Scores
      summary: Get scores
      operationId: getScores
      parameters:
        - name: user
          in: query
          schema:
            type: string
          example: abc123
        - name: quiz
          in: query
          schema:
            type: string
          example: Who we are
      responses:
        '200':
          description: Scores retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/score'
              example:
                - id: score_abc987def123
                  user: abc123
                  quiz: Who we are
                  score: 0.85
                  attempts: 1
        '400':
          $ref: '#/components/responses/badRequest'
  /users/{id}:
    get:
      tags:
        - Reports
      summary: Get user activity report
      operationId: getUserActivity
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: usr_abc123
      responses:
        '200':
          description: User activity details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/userDetail'
        '400':
          $ref: '#/components/responses/badRequest'
components:
  securitySchemes:
    imfKey:
      type: apiKey
      in: header
      name: IMF-KEY
  responses:
    badRequest:
      description: Bad request.
      content:
        application/problem+json:
          schema:
            type: object
            description: RFC7807 Problem Details
            properties:
              type:
                type: string
                format: uri
                example: https://example.com/errors/invalid-request
              title:
                type: string
                example: Invalid request
              status:
                type: integer
                example: 400
              detail:
                type: string
                example: One or more request fields are invalid.
              instance:
                type: string
                example: /quizzes
  schemas:
    userDetail:
      type: object
      description: Aggregated user activity report.
      additionalProperties: false
      properties:
        id:
          type: string
          example: usr_abc123
        activities:
          type: array
          items:
            $ref: '#/components/schemas/activity'
        quizzes:
          type: array
          items:
            $ref: '#/components/schemas/quiz'
        scores:
          type: array
          items:
            $ref: '#/components/schemas/score'
        badges:
          type: array
          items:
            type: string
            example: onboarding-complete
        lastActiveAt:
          type: string
          format: date-time
          example: '2023-02-19T11:00:00Z'
      required:
        - id
    score:
      type: object
      description: Quiz score achieved by a user.
      additionalProperties: false
      properties:
        id:
          type: string
          example: score_abc987def123
        user:
          type: string
          description: User identifier.
          example: abc123
        quiz:
          type: string
          description: Quiz name or identifier.
          example: Who we are
        score:
          type: number
          minimum: 0
          maximum: 1
          example: 0.85
        attempts:
          type: integer
          minimum: 1
          example: 1
        completedAt:
          type: string
          format: date-time
          example: '2023-02-19T10:12:00Z'
      required:
        - id
        - user
        - quiz
        - score
    activity:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          readOnly: true
          example: id_abc987def123
        data:
          type: object
          additionalProperties: false
          properties:
            type:
              type: string
              example: quiz
            name:
              type: string
              example: Onboarding Part 1
            item:
              type: string
              example: Sign agreements
            answer:
              type: string
              example: a
        metadata:
          type: object
          additionalProperties: false
          properties:
            user:
              type: string
              example: abc123
            domain:
              type: string
              format: url
              example: http://example.com
            path:
              type: string
              example: /security/network-security/
            timestamp:
              type: string
              format: date-time
              example: '2023-02-19T09:31:27Z'
    quiz:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          readOnly: true
          example: quiz_abc987def123
        name:
          type: string
          example: Who we are
        passingScore:
          type: number
          example: 0.8
