openapi: 3.1.0
info:
  title: Pokedex API
  version: 0.1.0
  description: REST API for the TrueLayer Pokémon challenge.
servers:
  - url: http://localhost:8000
paths:
  /health:
    get:
      summary: Health check
      responses:
        "200":
          description: Service is alive
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
  /pokemon/{name}:
    get:
      summary: Return basic Pokémon information
      parameters:
        - $ref: "#/components/parameters/PokemonName"
      responses:
        "200":
          description: Pokémon information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PokemonInfo"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/PokemonNotFound"
        "502":
          $ref: "#/components/responses/UpstreamFailure"
        "429":
          $ref: "#/components/responses/RateLimited"
  /pokemon/translated/{name}:
    get:
      summary: Return Pokémon information with a fun translated description
      description: Uses Yoda for legendary or cave Pokémon, Shakespeare otherwise. Falls back to the standard description when translation fails.
      parameters:
        - $ref: "#/components/parameters/PokemonName"
      responses:
        "200":
          description: Pokémon information with translated or fallback description
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PokemonInfo"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/PokemonNotFound"
        "502":
          $ref: "#/components/responses/UpstreamFailure"
        "429":
          $ref: "#/components/responses/RateLimited"
  /metrics:
    get:
      summary: OpenTelemetry metrics in Prometheus text format
      responses:
        "200":
          description: Prometheus text exposition
          content:
            text/plain:
              schema:
                type: string
components:
  parameters:
    PokemonName:
      name: name
      in: path
      required: true
      description: Pokémon identifier. Only ASCII letters, digits, and hyphens are accepted.
      schema:
        type: string
        pattern: "^[A-Za-z0-9-]+$"
      example: mewtwo
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: bad_request
            message: pokemon name must contain only ASCII letters, digits, or hyphens
            requestId: 7b2d6f7b-78ef-4cc3-85fd-5f09145fbd18
    PokemonNotFound:
      description: Pokémon was not found by PokéAPI
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: pokemon_not_found
            message: pokemon not found
            requestId: 7b2d6f7b-78ef-4cc3-85fd-5f09145fbd18
    UpstreamFailure:
      description: An upstream provider failed or returned invalid data
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            unavailable:
              value:
                code: upstream_unavailable
                message: upstream service failed
                requestId: 7b2d6f7b-78ef-4cc3-85fd-5f09145fbd18
            invalidData:
              value:
                code: upstream_invalid_data
                message: upstream service returned invalid data
                requestId: 7b2d6f7b-78ef-4cc3-85fd-5f09145fbd18
    RateLimited:
      description: Request was rate limited
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: rate_limit_exceeded
            message: rate limit exceeded
            requestId: 7b2d6f7b-78ef-4cc3-85fd-5f09145fbd18
  schemas:
    HealthResponse:
      type: object
      required: [status]
      properties:
        status:
          type: string
          const: ok
    PokemonInfo:
      type: object
      required: [name, description, habitat, isLegendary]
      properties:
        name:
          type: string
          example: mewtwo
        description:
          type: string
          example: It was created by a scientist after years of horrific gene splicing and DNA engineering experiments.
        habitat:
          type: string
          example: rare
        isLegendary:
          type: boolean
          example: true
    ErrorResponse:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          enum:
            - bad_request
            - pokemon_not_found
            - upstream_invalid_data
            - upstream_unavailable
            - rate_limit_exceeded
            - internal_error
        message:
          type: string
        requestId:
          type: string
          description: Request correlation id from x-request-id.