openapi: 3.0.3
info:
  title: Seduo Company API
  description: |
    ## Authentication
    API uses Bearer token authentication. Token can be obtained from Seduo administrator.
    Authentication is handled via CompanyApiAccessTokenHandler with role ROLE_COMPANY_API_USER.

    ## Rate Limiting
    - 10 requests per minute per company/IP combination (fixed window)
    - 100 requests per hour per company/IP combination (sliding window)
    - Rate limit exceeded returns HTTP 429 status with Retry-After header
    - Rate limit headers included in all responses:
      - X-RateLimit-Remaining-Minute
      - X-RateLimit-Remaining-Hour
      - X-RateLimit-Limit-Minute
      - X-RateLimit-Limit-Hour
  version: 1.0.0
  contact:
    name: Seduo Support
    email: support@seduo.com

servers:
  - url: https://{domain}/api/resources
    description: Production server
    variables:
      domain:
        default: www.seduo.cz
        description: Domain specific to your company

security:
  - BearerAuth: []
paths:
  /courses/{format}:
    get:
      tags:
        - Company API
      summary: Get standard courses catalog
      description: Returns a list of all standard courses available for the company
      parameters:
        - name: format
          in: path
          description: Response format
          required: true
          schema:
            type: string
            enum: [json, xml]
      responses:
        '200':
          description: Successful response
          headers:
            X-RateLimit-Remaining-Minute:
              description: Remaining requests in current minute window
              schema:
                type: integer
            X-RateLimit-Remaining-Hour:
              description: Remaining requests in current hour window
              schema:
                type: integer
            X-RateLimit-Limit-Minute:
              description: Maximum requests per minute
              schema:
                type: integer
            X-RateLimit-Limit-Hour:
              description: Maximum requests per hour
              schema:
                type: integer
            Cache-Control:
              description: Cache control header for XML responses
              schema:
                type: string
                example: "public, max-age=3600"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogResponse'
              examples:
                StandardCoursesExample:
                  $ref: '#/components/examples/StandardCoursesResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/CatalogResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /microlearning/{format}:
    get:
      tags:
        - Company API
      summary: Get microlearning courses catalog
      description: Returns a list of all microlearning courses available for the company
      parameters:
        - name: format
          in: path
          description: Response format
          required: true
          schema:
            type: string
            enum: [json, xml]
      responses:
        '200':
          description: Successful response
          headers:
            X-RateLimit-Remaining-Minute:
              description: Remaining requests in current minute window
              schema:
                type: integer
            X-RateLimit-Remaining-Hour:
              description: Remaining requests in current hour window
              schema:
                type: integer
            X-RateLimit-Limit-Minute:
              description: Maximum requests per minute
              schema:
                type: integer
            X-RateLimit-Limit-Hour:
              description: Maximum requests per hour
              schema:
                type: integer
            Cache-Control:
              description: Cache control header for XML responses
              schema:
                type: string
                example: "public, max-age=3600"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogResponse'
              examples:
                MicrolearningCoursesExample:
                  $ref: '#/components/examples/MicrolearningCoursesResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/CatalogResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalServerError'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API token provided by Seduo administrator

  schemas:
    CatalogResponse:
      type: object
      properties:
        generated_at:
          type: string
          format: date-time
          description: Timestamp when the catalog was generated
          example: "2023-12-31T23:00:00+00:00"
        company_name:
          type: string
          description: Name of the company
          example: "ACME Corporation"
        domain:
          type: string
          description: Domain from which the API request was made
          example: "www.seduo.cz"
        course_type:
          type: string
          enum: [standard, microlearning]
          description: Type of courses in this catalog
          example: "standard"
        total_courses:
          type: integer
          description: Total number of courses in the catalog
          example: 150
        courses:
          type: array
          items:
            $ref: '#/components/schemas/Course'

    Course:
      type: object
      properties:
        course_id:
          type: integer
          description: Unique course identifier
          example: 123
        course_name:
          type: string
          description: Course title
          example: "Introduction to Project Management"
        course_url:
          type: string
          format: uri
          description: URL to access the course (may require login)
          example: "https://www.seduo.cz/login?redirect=https://www.seduo.cz/course/project-management"
        lecturers:
          type: array
          items:
            type: string
          description: List of course lecturers
          example: ["John Doe", "Jane Smith"]
        categories:
          type: array
          items:
            type: string
          description: List of course categories
          example: ["Management", "Leadership"]
        abilities:
          type: array
          items:
            type: string
          description: List of skills/abilities taught
          example: ["Project Planning", "Team Management"]
        series:
          type: array
          items:
            type: string
          description: List of series this course belongs to (empty array if course is not part of any series)
          example: ["Management Fundamentals", "Leadership Series"]
        course_duration:
          type: integer
          description: Course duration in minutes (rounded up)
          minimum: 0
          example: 150
        image_url:
          type: string
          format: uri
          description: URL to course thumbnail image
          example: "https://cdn.seduo.cz/images/courses/project-management.jpg"
        video_url:
          type: string
          description: Direct URL to video stream (m3u8 format) or empty string if video is not available
          example: "https://video.seduo.cz/hls/course123/playlist.m3u8"
        claim:
          type: string
          description: Short course description or tagline
          example: "Learn essential project management skills"
        course_description:
          type: string
          description: Detailed course description
          example: "This comprehensive course covers all aspects of project management..."
        video_language:
          type: string
          description: Language code of the course video
          example: "cs"
        last_update:
          type: string
          format: date-time
          description: Timestamp when the course was last updated
          example: "2023-12-31T23:00:00+00:00"
        is_hidden:
          type: boolean
          description: Whether the course is hidden from public view
          example: false

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error type
          example: "Authentication failed"
        message:
          type: string
          description: Human-readable error message
          example: "Invalid API token"

  responses:
    BadRequestError:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: "Unsupported format"
            message: "Format \"txt\" is not supported. Supported formats: json, xml"
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example: |
            <?xml version="1.0" encoding="UTF-8"?>
            <error>
              <error>Unsupported format</error>
              <message>Format "txt" is not supported. Supported formats: json, xml</message>
            </error>

    UnauthorizedError:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: "Authentication failed"
            message: "Invalid API token"

    RateLimitError:
      description: Rate limit exceeded
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: "Rate limit exceeded"
            message: "Rate limit exceeded: Too many requests per minute. Please try again later."
        application/xml:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example: |
            <?xml version="1.0" encoding="UTF-8"?>
            <error>
              <error>Rate limit exceeded</error>
              <message>Rate limit exceeded: Too many requests per minute. Please try again later.</message>
            </error>

    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: "Internal server error"
            message: "Unable to generate catalog"

  examples:
    StandardCoursesResponse:
      summary: Example response for standard courses
      value:
        generated_at: "2023-12-31T23:00:00+00:00"
        company_name: "ACME Corporation"
        domain: "www.seduo.cz"
        course_type: "standard"
        total_courses: 2
        courses:
          - course_id: 123
            course_name: "Introduction to Project Management"
            course_url: "https://www.seduo.cz/login?redirect=https://www.seduo.cz/course/project-management"
            lecturers: ["John Doe", "Jane Smith"]
            categories: ["Management", "Leadership"]
            abilities: ["Project Planning", "Team Management"]
            series: ["Management Fundamentals"]
            course_duration: 150
            image_url: "https://cdn.seduo.cz/images/courses/project-management.jpg"
            video_url: "https://video.seduo.cz/hls/course123/playlist.m3u8"
            claim: "Learn essential project management skills"
            course_description: "This comprehensive course covers all aspects of project management..."
            video_language: "cs"
            last_update: "2023-12-31T23:00:00+00:00"
            is_hidden: false
          - course_id: 124
            course_name: "Advanced Excel Techniques"
            course_url: "https://www.seduo.cz/login?redirect=https://www.seduo.cz/course/excel-advanced"
            lecturers: ["Alice Johnson"]
            categories: ["IT", "Office Skills"]
            abilities: ["Excel", "Data Analysis"]
            series: ["Office Skills Mastery"]
            course_duration: 105
            image_url: "https://cdn.seduo.cz/images/courses/excel-advanced.jpg"
            video_url: "https://video.seduo.cz/hls/course124/playlist.m3u8"
            claim: "Master advanced Excel features"
            course_description: "Learn advanced Excel techniques for data analysis and reporting..."
            video_language: "cs"
            last_update: "2023-12-30T15:30:00+00:00"
            is_hidden: false

    MicrolearningCoursesResponse:
      summary: Example response for microlearning courses
      value:
        generated_at: "2023-12-31T23:00:00+00:00"
        company_name: "ACME Corporation"
        domain: "www.seduo.cz"
        course_type: "microlearning"
        total_courses: 1
        courses:
          - course_id: 201
            course_name: "Quick Time Management Tips"
            course_url: "https://www.seduo.cz/login?redirect=https://www.seduo.cz/microlearning/time-management"
            lecturers: ["Sarah Wilson"]
            categories: ["Productivity", "Personal Development"]
            abilities: ["Time Management", "Efficiency"]
            series: ["Productivity Essentials"]
            course_duration: 15
            image_url: "https://cdn.seduo.cz/images/courses/time-management.jpg"
            video_url: "https://video.seduo.cz/hls/course201/playlist.m3u8"
            claim: "Master time management in 15 minutes"
            course_description: "Quick and effective time management techniques for busy professionals..."
            video_language: "cs"
            last_update: "2023-12-29T10:00:00+00:00"
            is_hidden: false
