openapi: 3.1.1
info:
  title: Results Central API
  description: Official lottery results, by date and by lottery
  version: 1.0.0
paths:
  /v1/coverage:
    get:
      tags:
        - v1
      summary: Earliest and latest dates with an official result
      description: Earliest and latest dates with an official result
      operationId: v1.coverage
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Coverage'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: 'Seconds to wait before calling again: a whole number, at least 1.'
              required: true
              schema:
                type: integer
                minimum: 1.0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/lotteries:
    get:
      tags:
        - v1
      summary: The lotteries covered by the API
      description: The lotteries covered by the API
      operationId: v1.lotteries
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Lotteries'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: 'Seconds to wait before calling again: a whole number, at least 1.'
              required: true
              schema:
                type: integer
                minimum: 1.0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/lotteries/{id}/results:
    get:
      tags:
        - v1
      summary: One lottery's official draws over a date range, one day per date
      description: One lottery's official draws over a date range, one day per date
      operationId: v1.lottery_results
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/LotteryId'
        - name: from
          in: query
          required: true
          schema:
            type: string
            pattern: '^\d{4}-\d{2}-\d{2}$'
        - name: to
          in: query
          required: true
          schema:
            type: string
            pattern: '^\d{4}-\d{2}-\d{2}$'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1LotteryResults'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: 'Seconds to wait before calling again: a whole number, at least 1.'
              required: true
              schema:
                type: integer
                minimum: 1.0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/results:
    get:
      tags:
        - v1
      summary: Official draws on one local date
      description: Official draws on one local date
      operationId: v1.results
      parameters:
        - name: date
          in: query
          required: true
          schema:
            type: string
            pattern: '^\d{4}-\d{2}-\d{2}$'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Day'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: 'Seconds to wait before calling again: a whole number, at least 1.'
              required: true
              schema:
                type: integer
                minimum: 1.0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorCode:
      type: string
      enum:
        - internal
        - method.not_allowed
        - not_found
        - request.invalid
        - request.param.invalid
        - request.too_large
        - v1.plan_history
        - v1.quota_exceeded
        - v1.rate_limited
        - v1.unauthorized
      x-enum-varnames:
        - Internal
        - MethodNotAllowed
        - NotFound
        - RequestInvalid
        - RequestParamInvalid
        - RequestTooLarge
        - V1PlanHistory
        - V1QuotaExceeded
        - V1RateLimited
        - V1Unauthorized
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorCode'
        params:
          type: object
          additionalProperties:
            type: string
    LotteryId:
      type: integer
      format: int32
      minimum: 1.0
    V1Coverage:
      type: object
      required:
        - earliest
        - latest
      properties:
        earliest:
          type: string
          pattern: '^\d{4}-\d{2}-\d{2}$'
        latest:
          type: string
          pattern: '^\d{4}-\d{2}-\d{2}$'
    V1Day:
      type: object
      required:
        - date
        - generatedAt
        - draws
      properties:
        date:
          type: string
          pattern: '^\d{4}-\d{2}-\d{2}$'
        draws:
          type: array
          items:
            $ref: '#/components/schemas/V1Draw'
        generatedAt:
          type: string
          format: date-time
    V1Draw:
      type: object
      required:
        - id
        - lotteryId
        - lottery
        - sortition
        - country
        - date
        - drawAt
        - numbers
      properties:
        country:
          type: string
          enum:
            - unitedStates
            - dominicanRepublic
            - haiti
            - anguilla
            - sintMaarten
            - honduras
            - elSalvador
            - bonaire
            - panama
        date:
          type: string
          pattern: '^\d{4}-\d{2}-\d{2}$'
        drawAt:
          type: string
          format: date-time
        id:
          type: string
          minLength: 1
        lottery:
          type: string
          minLength: 1
        lotteryId:
          $ref: '#/components/schemas/LotteryId'
        numbers:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/V1Number'
        sortition:
          type: string
          minLength: 1
    V1Lotteries:
      type: object
      required:
        - lotteries
      properties:
        lotteries:
          type: array
          items:
            $ref: '#/components/schemas/V1Lottery'
    V1Lottery:
      type: object
      required:
        - id
        - name
        - slug
        - schedule
      properties:
        id:
          $ref: '#/components/schemas/LotteryId'
        name:
          type: string
          minLength: 1
        schedule:
          type: array
          items:
            type: integer
            format: int32
        slug:
          type: string
          minLength: 1
          pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
    V1LotteryResults:
      type: object
      required:
        - lottery
        - days
      properties:
        days:
          type: array
          items:
            $ref: '#/components/schemas/V1Day'
        lottery:
          type:
            - object
            - 'null'
          required:
            - id
            - name
            - slug
            - schedule
          properties:
            id:
              $ref: '#/components/schemas/LotteryId'
            name:
              type: string
              minLength: 1
            schedule:
              type: array
              items:
                type: integer
                format: int32
            slug:
              type: string
              minLength: 1
              pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
    V1Number:
      type: object
      required:
        - field
        - display
      properties:
        display:
          description: Zero-padded to the field's length
          type: string
          minLength: 1
        field:
          type: string
          enum:
            - first
            - second
            - third
            - pickTwo
            - pickThree
            - pickFour
            - pickFive
            - pickFourSecond
            - pickFourThird
