openapi: 3.0.3
info:
  version: v1.0.3
  title: LE-KO Coach Explorer API
  license:
    name: private
    url: https://le-ko.deggex.com
  contact:
    email: denis@deggex.awsapps.com
  description: LE-KO API for exploring and finding coaches.
servers:
  - url: https://booking-{env}.le-ko.deggex.com/{basePath}
    description: Coach Explorer APIs.
    variables:
      basePath:
        default: v1
      env:
        default: dev
security:
  - bearerHttpAuthentication: []
tags:
  - name: explorer
    description: APIs related to finding and exploring coaches.
paths:
  /coach-recommendations/{athleteId}:
    get:
      operationId: getCoachRecommendations
      summary: Get starter coach recommendations for an athlete
      description: |
        ✨ Retrieves up to 5 coach recommendations tailored for a specific athlete to facilitate discovery
      tags:
        - explorer
      parameters:
        - name: athleteId
          in: path
          required: true
          description: The ID of the athlete for whom to get recommendations.
          schema:
            $ref: '#/components/schemas/Id'
        - name: latitude
          in: query
          required: false
          description: Optional latitude to inform user of coach distance.
          schema:
            type: number
            format: float
        - name: longitude
          in: query
          required: false
          description: Optional longitude to inform user of coach distance.
          schema:
            type: number
            format: float
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: A list of recommended coaches for the athlete.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Coach'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /coach-recommendations/filter:
    get:
      summary: Get filtered coaches
      operationId: getFilteredCoaches
      description: ✨ Lists coaches according to a set of filters.
      tags:
        - explorer
      parameters:
        - name: coachIds
          description: Coaches to filter by. Mainly used to filter through recommended coaches.
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              format: uuid
          style: form
          explode: false
        - name: sportIds
          in: query
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Id'
          style: form
          explode: false
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum:
              - online
              - offline
        - name: sessionType
          in: query
          required: false
          schema:
            type: string
            enum:
              - group
              - personal
        - name: skill
          in: query
          required: false
          schema:
            type: string
            enum:
              - beginner
              - intermediate
              - pro
              - all
        - name: ageFrom
          in: query
          required: false
          schema:
            type: integer
        - name: ageTo
          in: query
          required: false
          schema:
            type: integer
        - name: locationMaxDistanceMeters
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
        - name: locationUserLatitude
          in: query
          required: false
          schema:
            type: number
            format: double
        - name: locationUserLongitude
          in: query
          required: false
          schema:
            type: number
            format: double
          explode: true
        - name: minPrice
          in: query
          required: false
          description: Minimum (inclusive) price
          schema:
            type: integer
            minimum: 0
        - name: maxPrice
          in: query
          required: false
          description: Maximum (inclusive) price
          schema:
            type: integer
            minimum: 0
        - name: eligibility
          in: query
          required: false
          description: Filter coaches by gender eligibility (men, women, or all)
          schema:
            type: string
            enum:
              - men
              - women
              - all
        - name: startTime
          in: query
          required: false
          description: Filter coaches which have sessions starting at around this time. Although date-time is used, only the time is relevant for filtering.
          schema:
            type: string
            format: date-time
        - name: endTime
          in: query
          required: false
          description: Filter coaches which have sessions ending at around this time. Although date-time is used, only the time is relevant for filtering.
          schema:
            type: string
            format: date-time
        - name: userId
          in: query
          required: false
          description: The ID of the user performing the request. Used to filter them out of results.
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: A list of coach IDs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FilterResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /coach-recommendations/{coachId}/summary:
    get:
      summary: Get summary of coach services
      operationId: getCoachServiceSummary
      description: ✨ Returns a summary of coach services
      tags:
        - explorer
      parameters:
        - name: coachId
          in: path
          required: true
          description: Identifier of the coach.
          schema:
            type: string
            format: uuid
        - name: userLatitude
          in: query
          required: false
          description: User latitude. Used to calculate distance.
          schema:
            type: number
            format: double
        - name: userLongitude
          in: query
          required: false
          description: User longitude. Used to calculate distance.
          schema:
            type: number
            format: double
        - name: serviceId
          in: query
          required: false
          description: May be used to get the summary of the coach for a specific service. Useful when the coach offers multiple services and you need a summary for a particular one.
          schema:
            type: string
            format: uuid
        - name: timeslotIds
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: A summary of the services provided by the coach.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoachServiceSummary'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Coach not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    bearerHttpAuthentication:
      description: Bearer token using a JWT
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Id:
      type: string
      example: 4b72d209-debd-45e1-93cc-7640bf7d39bf
      description: Database entity primary key uuid
      format: uuid
      maxLength: 36
      minLength: 36
      pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
    Coach:
      type: object
      description: Represents key information about a coach relevant for discovery and display in explorer lists or recommendations. Includes details like location relative to the user, and service ranges (price, duration). Further details, such as name and username, must be filled in by CoreAPI. Fields marked as nullable may be null if the coach has not yet created associated services or if the specific data point (e.g., distance, price range) is otherwise unavailable for that coach.
      required:
        - coachId
        - sportId
        - coachServicePictureIds
        - formattedAddress
        - distanceFromUser
        - priceRangeStart
        - priceRangeEnd
        - timeRangeStart
        - timeRangeEnd
      properties:
        coachId:
          $ref: '#/components/schemas/Id'
        sportId:
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Id'
        coachServicePictureIds:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/Id'
        formattedAddress:
          description: A single string representing the coach's primary location or service area.
          type: string
          nullable: true
        distanceFromUser:
          description: The distance, in meters, from the requesting user. Null if no geo location is provided.
          type: integer
          nullable: true
        priceRangeStart:
          type: integer
          nullable: true
        priceRangeEnd:
          type: integer
          nullable: true
        timeRangeStart:
          description: Minimum session duration offered by the coach, in minutes.
          type: integer
          nullable: true
        timeRangeEnd:
          description: Maximum session duration offered by the coach, in minutes.
          type: integer
          nullable: true
    Error:
      type: object
      required:
        - code
        - message
        - endpoint
        - requestId
      properties:
        code:
          type: string
          description: Error unique code
          enum:
            - validation
            - internal
            - oops
            - unexpected
            - tooManyRequests
            - notFound
            - unauthorized
            - forbidden
        message:
          type: string
          description: Error message
        endpoint:
          type: string
        requestId:
          type: string
    Errors:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    FilterResponse:
      type: object
      required:
        - coachId
        - serviceId
        - timeSlotIds
      properties:
        coachId:
          type: string
          format: uuid
        serviceId:
          type: string
          format: uuid
        timeSlotIds:
          type: array
          items:
            type: string
            format: uuid
    CoachServiceSummary:
      type: object
      required:
        - mainServiceId
        - mainSportId
        - mainServicePhotoIds
        - formattedAddress
        - priceRangeMin
        - priceRangeMax
        - durationMin
        - durationMax
        - distanceFromUser
        - serviceSkillLevels
        - serviceEligibilities
      properties:
        mainServiceId:
          type: string
          format: uuid
          nullable: true
        mainSportId:
          type: string
          format: uuid
          nullable: true
        mainServicePhotoIds:
          type: array
          nullable: true
          items:
            type: string
            format: uuid
        formattedAddress:
          type: string
          nullable: true
        priceRangeMin:
          type: integer
          nullable: true
        priceRangeMax:
          type: integer
          nullable: true
        durationMin:
          type: integer
          nullable: true
        durationMax:
          type: integer
          nullable: true
        distanceFromUser:
          type: integer
          nullable: true
          description: The distance from user in meters.
        serviceSkillLevels:
          type: array
          items:
            type: string
        serviceEligibilities:
          type: array
          items:
            type: string
  parameters:
    TraceparentHeader:
      name: traceparent
      in: header
      required: false
      description: W3C Trace Context traceparent header for request tracing
      schema:
        type: string
        pattern: ^[0-9a-f]{2}-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$
        example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01