openapi: 3.0.0
info:
  title: leaderboard
  version: 1.0.0
  termsOfService: https://antavo.com/legals/terms
  contact:
    email: support@antavo.com
security:
  - api_key: []
paths:
  /customers/leaderboard:
    get:
      tags:
        - Leaderboard
      summary: Returns best performing customers
      parameters:
        - name: limit
          in: query
          description: The number of results to return. Values outside the acceptance range
            will be automatically changed to the nearest boundary value.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: offset
          in: query
          description: "The interval in which the leaderboard standings should be returned.
            Accepted values: overall, week, month"
          schema:
            type: string
            default: overall
      responses:
        "200":
          description: Customer leaderboard data
          content:
            "*/*":
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Response"
                  - $ref: "#/components/schemas/error"        
              examples:
                success:
                  summary: Successful submission
                  value:
                    id: "4hd1f4xlnd3zcufjagtn"
                    handler: "fullmoonGirl"
                    image_url: "https://unsplash.it/200/300/?random"
                    score: 49621
                # fail:
                #   summary: "Error - Customer is not in the system or opted out"
                #   value:
                #     code: 160602 
                #     message: Invalid customer ID
        # "404":
        #   description: "Leadership module is not enabled"
        #   content:
        #     "*/*":
        #       schema:
        #         $ref: "#/components/schemas/ErrorResponse"
servers:
  - url: https://api.academy.antavo.com
    description: The Antavo Academy
  - url: https://api.rc.antavo.com
    description: The Antavo rc test environment
  - url: https://api.salesdemo.antavo.com
    description: The Antavo Sales demonstration environment
  - url: https://api.staging.antavo.com
    description: The Antavo staging environment



components:
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      description: Provides API Key access to the endpoint
      in: query
  schemas:
    error:
      description: Detailed breakdown of an Antavo-related error
      type: object
      required:
        - type
        - code
        - message
      properties:
        type:
          type: string
          description: "Type of the error occurred, e.g.: `BadRequestException`,
            `NotFoundException`"
          example: RuntimeException
        code:
          type: number
          description: A 6-digit number to uniquely identify the place the error occurred
          example: 160201
        message:
          type: string
          description: Human readable error message
          example: Leaderboard extension is not enabled
    Response:
      type: array
      description: An array of Leaderboard items
      items:
        $ref: "#/components/schemas/LeaderboardItem"
     
    LeaderboardItem:
      type: object
      required:
        - id
        - handler
        - image_url
        - score
      properties:
        id:
          type: string
          description: The unique customer loyalty identifier
          example: "123456789"
        handler:
          type: string
          description: The customer's handler (nickname). If not set, this will return the
            customer's first name or null.
          example: Nickname
        image_url:
          type: string
          description: The avatar of the customer. Returns null If not set
          example: https://example.com/image.png
        score:
          type: integer
          description: The points earned by the customer in the given interval
          example: 12345
