openapi: 3.0.1
info:
  title: Rockstar Music Teacher Recommendations API
  version: 1.0.0
  description: |
    Simplified access to Rockstar Music’s teacher directory to help users discover
    in-home and online music teachers by region and instrument.

    Use cases:
    - List supported regions (/api/regions)
    - List supported instruments and aliases (/api/instruments)
    - Get recommended teachers for a region + instrument (/api/recommend)

    Privacy:
    - Responses are sanitized and do not expose private contact info.

  contact:
    name: Rockstar Music Central
    url: https://rockstarmusic.ca/contact

servers:
  - url: https://rockstarmusic.ca
    description: Production

tags:
  - name: Directory
    description: Regions, instruments, and teacher recommendations.

paths:
  /api/regions:
    get:
      tags: [Directory]
      operationId: getRegions
      summary: List supported regions
      description: |
        Returns teaching regions supported by Rockstar Music.
        Use the "slug" field to build region-based URLs.
      responses:
        "200":
          description: A JSON array of regions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Region"
              examples:
                sample:
                  value:
                    - id: 1
                      name: Toronto
                      slug: toronto
                    - id: 2
                      name: Vancouver
                      slug: vancouver,_bc
        "500":
          $ref: "#/components/responses/ServerError"

  /api/instruments:
    get:
      tags: [Directory]
      operationId: getInstruments
      summary: List supported instruments (with aliases)
      description: |
        Returns instruments Rockstar supports. "aliases" includes alternate spellings/names
        that can be used when querying /api/recommend.
      responses:
        "200":
          description: A JSON array of instruments.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Instrument"
              examples:
                sample:
                  value:
                    - id: 1
                      name: Guitar
                      aliases: ["guitar", "electric guitar", "acoustic guitar"]
                    - id: 2
                      name: Piano
                      aliases: ["piano", "keys", "keyboard"]
        "500":
          $ref: "#/components/responses/ServerError"

  /api/recommend:
    get:
      tags: [Directory]
      operationId: getRecommendedTeachers
      summary: Get recommended teachers by region and instrument
      description: |
        Returns a list of recommended teachers for the given region and instrument.

        Notes:
        - "instrument" can be a common instrument name (e.g., "guitar") or one of the aliases from /api/instruments.
        - "region" can be a region name (e.g., "Toronto") or a region slug (e.g., "toronto") from /api/regions.
        - Use "limit" to cap returned results (useful for UI previews).
      parameters:
        - name: instrument
          in: query
          required: true
          description: Instrument name or alias (e.g., "guitar", "piano").
          schema:
            type: string
            minLength: 1
          examples:
            guitar:
              value: guitar
            piano:
              value: piano

        - name: region
          in: query
          required: true
          description: Region name or slug (e.g., "Toronto" or "toronto").
          schema:
            type: string
            minLength: 1
          examples:
            torontoName:
              value: Toronto
            torontoSlug:
              value: toronto

        - name: limit
          in: query
          required: false
          description: Optional max teachers to return.
          schema:
            type: integer
            minimum: 1
            maximum: 50
          examples:
            five:
              value: 5

      responses:
        "200":
          description: Recommendations response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TeacherResponse"
              examples:
                sample:
                  value:
                    count: 2
                    teachers:
                      - id: 51028
                        name: Sam Wood
                        instruments: "Guitar, Bass"
                        styles: "Rock, Pop"
                        levels: "Beginner, Intermediate"
                        languages: "English"
                        description: "Patient instructor focused on building confidence and fundamentals."
                        profileImageUrl: "https://rockstartimageblog.blob.core.windows.net/images/teacher/c8acc5bf-955e-4a02-9d6b-f1f400cbca01.jpg"
                      - id: 41011
                        name: Andrea Chin
                        instruments: "Piano"
                        styles: "Classical, Pop"
                        levels: "Beginner"
                        languages: "English"
                        description: "Supportive lessons tailored to each student."
                        profileImageUrl: "https://rockstartimageblog.blob.core.windows.net/images/teacher/551a400a-f494-44dd-9e27-06be42358f74.jpeg"

        "400":
          description: Missing or invalid parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                missing:
                  value:
                    error: "Missing instrument or region parameter."

        "404":
          description: Region or instrument not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                regionNotFound:
                  value:
                    error: "Region not found."
                instrumentNotFound:
                  value:
                    error: "Instrument not found."

        "500":
          $ref: "#/components/responses/ServerError"

components:
  responses:
    ServerError:
      description: Server error.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            server:
              value:
                error: "Internal server error."

  schemas:
    Region:
      type: object
      description: A supported teaching region.
      properties:
        id:
          type: integer
          description: Unique region identifier.
          example: 2
        name:
          type: string
          description: Region display name.
          example: Vancouver
        slug:
          type: string
          description: URL-friendly slug for the region (used in URLs).
          example: vancouver,_bc
      required: [id, name, slug]
      additionalProperties: true

    Instrument:
      type: object
      description: An instrument and its recognized aliases.
      properties:
        id:
          type: integer
          description: Unique instrument identifier.
          example: 1
        name:
          type: string
          description: Canonical instrument name.
          example: Guitar
        aliases:
          type: array
          description: Alternative names/keywords for this instrument.
          items:
            type: string
          example: ["guitar", "electric guitar", "acoustic guitar"]
      required: [id, name, aliases]
      additionalProperties: true

    TeacherSummary:
      type: object
      description: Sanitized teacher summary (no private contact info).
      properties:
        id:
          description: Unique teacher identifier.
          oneOf:
            - type: integer
            - type: string
          example: 51028
        name:
          type: string
          description: Teacher’s full name.
          example: Sam Wood
        instruments:
          type: string
          description: Instruments taught (human-readable).
          example: "Guitar, Bass"
        styles:
          type: string
          description: Comma-separated music styles.
          example: "Rock, Pop"
        levels:
          type: string
          description: Comma-separated student levels.
          example: "Beginner, Intermediate"
        languages:
          type: string
          description: Languages spoken.
          example: "English"
        description:
          type: string
          description: Sanitized teacher bio/description.
          example: "Patient instructor focused on building confidence and fundamentals."
        profileImageUrl:
          type: string
          format: uri
          description: URL to a public profile image.
          example: "https://rockstartimageblog.blob.core.windows.net/images/teacher/c8acc5bf-955e-4a02-9d6b-f1f400cbca01.jpg"
      required: [id, name]
      additionalProperties: true

    TeacherResponse:
      type: object
      description: A list of recommended teachers.
      properties:
        count:
          type: integer
          description: Total number of teachers returned.
          example: 12
        teachers:
          type: array
          items:
            $ref: "#/components/schemas/TeacherSummary"
      required: [count, teachers]
      additionalProperties: true

    Error:
      type: object
      properties:
        error:
          type: string
      required: [error]
      additionalProperties: true