openapi: 3.0.3
info:
  title: Engagifii Training & Accreditation API
  version: 1.0.0
  description: |
    Comprehensive enterprise-level API for managing professional training, certifications, and educational programs.
    
    The API provides complete lifecycle management for:
    - Awards and certifications
    - Class scheduling and management  
    - Course curriculum development
    - Registration workflows with approval chains
    - Credit management and tracking
    - Multi-tenant operations with secure data isolation
    
    All endpoints require a tenant-code header for multi-tenant isolation.
  contact:
    name: API Support
    email: api-support@engagifii.com
    url: https://support.engagifii.com
  license:
    name: Proprietary
    url: https://www.engagifii.com/terms
  x-logo:
    url: https://www.engagifii.com/logo.png
    altText: Engagifii Logo

servers:
  - url: https://engagifii-trainingandaccreditation.azurewebsites.net
    description: Production server
  - url: https://staging-engagifii-trainingandaccreditation.azurewebsites.net
    description: Staging server (Contact admin for access)
  - url: https://dev-engagifii-trainingandaccreditation.azurewebsites.net
    description: Development server (Contact admin for access)

security:
  - tenantCode: []
  - bearerAuth: []
    tenantCode: []

tags:
  - name: Awards
    description: Manage certifications, credentials, and professional achievements
  - name: Classes
    description: Handle class creation, scheduling, and session management
  - name: Courses
    description: Course curriculum and educational content management
  - name: Registration
    description: Registration workflows, approvals, and enrollment management
  - name: Credits
    description: Credit requests, transfers, and earned credit tracking
  - name: People
    description: Member and user management
  - name: Organizations
    description: Organizational hierarchy and company management
  - name: Reports
    description: Analytics, statistics, and reporting endpoints
  - name: Settings
    description: System configuration and tenant settings
  - name: Notifications
    description: Notification management and communication

paths:
  /api/v1/Awards/List:
    get:
      tags:
        - Awards
      summary: Get list of awards
      description: Retrieve all awards for the tenant with optional date filtering
      operationId: getAwardsList
      parameters:
        - $ref: '#/components/parameters/tenantCode'
        - name: selectedDate
          in: query
          description: Filter awards by selected date
          required: false
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Award'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /api/v1/Awards/{id}:
    get:
      tags:
        - Awards
      summary: Get award details
      description: Retrieve detailed information about a specific award
      operationId: getAwardById
      parameters:
        - $ref: '#/components/parameters/tenantCode'
        - $ref: '#/components/parameters/awardId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardDetail'
        '404':
          $ref: '#/components/responses/NotFound'
    
    put:
      tags:
        - Awards
      summary: Update award
      description: Update an existing award's information
      operationId: updateAward
      parameters:
        - $ref: '#/components/parameters/tenantCode'
        - $ref: '#/components/parameters/awardId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardUpdateRequest'
      responses:
        '200':
          description: Award updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardDetail'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
    
    delete:
      tags:
        - Awards
      summary: Delete award
      description: Delete an award from the system
      operationId: deleteAward
      parameters:
        - $ref: '#/components/parameters/tenantCode'
        - $ref: '#/components/parameters/awardId'
      responses:
        '204':
          description: Award deleted successfully
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Conflict - Award has active registrations

  /api/v1/Awards:
    post:
      tags:
        - Awards
      summary: Create award
      description: Create a new award or certification
      operationId: createAward
      parameters:
        - $ref: '#/components/parameters/tenantCode'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardCreateRequest'
      responses:
        '201':
          description: Award created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Award'
          headers:
            Location:
              description: URL of the created award
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/registration/ClassRegistration:
    post:
      tags:
        - Registration
      summary: Register for class
      description: Register a member for a class session
      operationId: createClassRegistration
      parameters:
        - $ref: '#/components/parameters/tenantCode'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClassRegistrationRequest'
      responses:
        '201':
          description: Registration created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          description: Conflict - Already registered
        '422':
          description: Business rule violation - Class full or registration closed

components:
  securitySchemes:
    tenantCode:
      type: apiKey
      in: header
      name: tenant-code
      description: Required tenant identifier for multi-tenant data isolation
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Optional JWT bearer token for enhanced security

  parameters:
    tenantCode:
      name: tenant-code
      in: header
      description: Tenant identifier for data isolation
      required: true
      schema:
        type: string
        example: tenant-12345
    
    awardId:
      name: id
      in: path
      description: Award unique identifier
      required: true
      schema:
        type: string
        format: uuid
        example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
    
    page:
      name: page
      in: query
      description: Page number (1-based)
      schema:
        type: integer
        minimum: 1
        default: 1
    
    pageSize:
      name: pageSize
      in: query
      description: Number of items per page
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
    
    sortBy:
      name: sortBy
      in: query
      description: Field to sort by
      schema:
        type: string
    
    sortDirection:
      name: sortDirection
      in: query
      description: Sort direction
      schema:
        type: string
        enum: [asc, desc]
        default: asc

  schemas:
    Award:
      type: object
      required:
        - id
        - name
        - isActive
        - createdDate
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 200
          description: Award name
        description:
          type: string
          maxLength: 2000
          description: Award description
        levelType:
          type: string
          description: Level type (e.g., Beginner, Advanced)
        objectType:
          type: string
          description: Object type (e.g., Certification, Badge)
        price:
          type: number
          format: decimal
          minimum: 0
          description: Award price
        isActive:
          type: boolean
          default: true
          description: Whether award is active
        tags:
          type: array
          items:
            type: string
          description: Award tags
        skills:
          type: array
          items:
            type: string
          description: Skills associated with award
        createdDate:
          type: string
          format: date-time
          description: Creation timestamp
          readOnly: true
        modifiedDate:
          type: string
          format: date-time
          description: Last modification timestamp
          readOnly: true

    AwardDetail:
      allOf:
        - $ref: '#/components/schemas/Award'
        - type: object
          properties:
            requirements:
              type: string
              description: Entry requirements
            duration:
              type: string
              description: Expected duration
            allowSelfRegistration:
              type: boolean
              description: Allow self-registration
            requiresApproval:
              type: boolean
              description: Requires approval for registration
            prerequisites:
              type: array
              items:
                $ref: '#/components/schemas/Prerequisite'
            validityPeriod:
              $ref: '#/components/schemas/ValidityPeriod'

    AwardCreateRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type: string
          maxLength: 2000
        levelTypeId:
          type: string
          format: uuid
        objectTypeId:
          type: string
          format: uuid
        requirements:
          type: string
        price:
          type: number
          format: decimal
          minimum: 0
        duration:
          type: string
        isActive:
          type: boolean
          default: true
        allowSelfRegistration:
          type: boolean
          default: false
        requiresApproval:
          type: boolean
          default: true
        tags:
          type: array
          items:
            type: string
        skills:
          type: array
          items:
            type: string

    AwardUpdateRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type: string
          maxLength: 2000
        price:
          type: number
          format: decimal
          minimum: 0
        isActive:
          type: boolean
        tags:
          type: array
          items:
            type: string

    ClassRegistrationRequest:
      type: object
      required:
        - classId
        - memberId
      properties:
        classId:
          type: string
          format: uuid
          description: Class to register for
        memberId:
          type: string
          format: uuid
          description: Member being registered
        registrationType:
          type: string
          enum: [Self, Manager, Admin]
          default: Self
        justification:
          type: string
          maxLength: 1000
        paymentMethod:
          type: string
          enum: [CreditCard, PurchaseOrder, Invoice, Free]
        notes:
          type: string
          maxLength: 500

    RegistrationResponse:
      type: object
      properties:
        registrationId:
          type: string
          format: uuid
        status:
          type: string
          enum: [Confirmed, PendingApproval, Waitlisted]
        confirmationNumber:
          type: string
        message:
          type: string

    Prerequisite:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        type:
          type: string
          enum: [Course, Award, Experience]

    ValidityPeriod:
      type: object
      properties:
        years:
          type: integer
          minimum: 0
          maximum: 99
        months:
          type: integer
          minimum: 0
          maximum: 11
        days:
          type: integer
          minimum: 0
          maximum: 365

    Error:
      type: object
      required:
        - error
        - status
        - timestamp
        - path
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code
            message:
              type: string
              description: Human-readable error message
            target:
              type: string
              description: Field or parameter that caused the error
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  target:
                    type: string
        status:
          type: integer
          description: HTTP status code
        timestamp:
          type: string
          format: date-time
        path:
          type: string
          description: API endpoint path
        requestId:
          type: string
          description: Unique request identifier

  responses:
    BadRequest:
      description: Bad request - validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: VALIDATION_ERROR
              message: One or more validation errors occurred
              details:
                - code: REQUIRED_FIELD
                  target: name
                  message: Name is required
            status: 400
            timestamp: '2024-01-20T10:30:45Z'
            path: /api/v1/Awards
            requestId: req-123e4567-e89b-12d3-a456-426614174000

    Unauthorized:
      description: Unauthorized - authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: AUTHENTICATION_REQUIRED
              message: Authentication is required for this request
            status: 401
            timestamp: '2024-01-20T10:30:45Z'
            path: /api/v1/Awards

    Forbidden:
      description: Forbidden - insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: RESOURCE_NOT_FOUND
              message: The requested resource was not found
            status: 404
            timestamp: '2024-01-20T10:30:45Z'
            path: /api/v1/Awards/123

    TooManyRequests:
      description: Too many requests - rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        X-RateLimit-Limit:
          description: Request limit per minute
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Remaining requests
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Time when limit resets (Unix timestamp)
          schema:
            type: integer
        Retry-After:
          description: Seconds to wait before retry
          schema:
            type: integer

    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_SERVER_ERROR
              message: An unexpected error occurred
            status: 500
            timestamp: '2024-01-20T10:30:45Z'
            path: /api/v1/Awards
            requestId: req-123e4567-e89b-12d3-a456-426614174000

# Note: This is a simplified OpenAPI specification showing key endpoints.
# The complete API contains 800+ endpoints across 40+ resource categories.
# Download the full specification from: /docs/openapi.json