feat: document api contract

openapi.yaml

@@ -0,0 +1,170 @@
+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:5000
+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.