openapi: 3.1.0
info:
  title: Metadata Endpoints API
  description: Standardized metadata endpoints for monitoring and managing applications based on [Kong AIP 3100](https://kong-aip.netlify.app/aip/3100/)
  version: 1.0.0
  contact:
    name: Kong AIP working group
    url: https://github.com/Kong/aip
servers:
  - url: '{baseUrl}/health'
    description: Base path for all metadata endpoints
    variables:
      baseUrl:
        default: 'http://localhost:8080'
        description: Base URL of the service

paths:
  /metrics:
    get:
      summary: Application metrics
      description: Returns application metrics in [Prometheus exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/)
      operationId: getMetrics
      tags:
        - Metrics
      responses:
        '200':
          description: Metrics in Prometheus exposition format
          content:
            text/plain:
              schema:
                type: string
                description: Metrics in Prometheus exposition format v0.0.4 or above
              example: |
                # HELP http_requests_total The total number of HTTP requests.
                # TYPE http_requests_total counter
                http_requests_total{method="post",code="200"} 1027 1395066363000
                http_requests_total{method="post",code="400"} 3 1395066363000
  /up:
    get:
      summary: Application status
      description: Returns basic information about the application and its status
      operationId: getUp
      tags:
        - Status
      responses:
        '200':
          description: Application is up and running
          content:
            application/json:
              schema:
                $ref: '#/components/responses/Up'
  /dependencies:
    get:
      summary: Dependencies status
      description: Returns a list of dependencies and their status
      operationId: getDependencies
      tags:
        - Status
      responses:
        '200':
          description: Dependencies status information
          content:
            application/json:
              schema:
                $ref: '#/components/responses/Dependencies'

  /probes/liveness:
    get:
      summary: Liveness probe
      description: Returns 200 if the application is alive
      operationId: getLivenessProbe
      tags:
        - Probes
      responses:
        '200':
          description: Application is alive
        '500':
          description: Application is not alive

  /probes/readiness:
    get:
      summary: Readiness probe
      description: Returns 200 if the application is ready to receive traffic
      operationId: getReadinessProbe
      tags:
        - Probes
      responses:
        '200':
          description: Application is ready to receive traffic
        '500':
          description: Application is not ready to receive traffic

  /probes/startup:
    get:
      summary: Startup probe
      description: Returns 200 if the application is ready to start receiving traffic
      operationId: getStartupProbe
      tags:
        - Probes
      responses:
        '200':
          description: Application is ready to start receiving traffic
        '500':
          description: Application is not ready to start receiving traffic

components:
  responses:
    Up:
      $ref: '#/components/schemas/Up'
    Dependencies:
      $ref: '#/components/schemas/Dependencies'
  schemas:
    Up:
      type: object
      description: Response model for the /up endpoint. This is a backbone and more strict schema should probably be added
      required:
        - status
        - version
        - commit
        - build_date
        - server_timestamp
        - service_version
        - service_name
      properties:
        server_timestamp:
          type: string
          format: date-time
          description: Timestamp when the response was generated
          example: 2025-03-05T14:00:00Z
        service_version:
          type: string
          description: Version of the service
          example: v1.0.0
        service_commit_sha:
          type: string
          description: Commit SHA of the service
          example: a1b2c3d4
        env:
          type: string
          description: Environment where the application is running
          example: production
        geo:
          type: string
          description: Geo the app is deployed in
          example: us
        region:
          type: string
          description: Region the app is deployed in
          example: us-west
        service_name:
          type: string
          description: Name of the service
          example: my-service
    Dependencies:
      type: object
      description: Response model for the /dependencies endpoint
      required:
        - status
        - dependencies
      properties:
        status:
          $ref: '#/components/schemas/DependencyStatus'
          description: Overall status of all dependencies
        dependencies:
          type: object
          description: List of dependencies
          additionalProperties:
            $ref: '#/components/schemas/Dependency'
      example:
        status: up
        dependencies:
          postgres:
            name: postgres
            type: hard
            status: up
          redis:
            name: redis
            type: soft
            status: down
    DependencyStatus:
      type: string
      description: Dependency status (unknown can be used to indicate that the status of the dependency is not computed).
      enum: [up, down, degraded, unknown]
      example: up
    Dependency:
      type: object
      description: Single dependency information
      required:
        - name
        - type
        - status
      properties:
        name:
          type: string
          description: Dependency name
          example: postgres
        type:
          type: string
          enum: [hard, soft]
          description: Whether the dependency is hard (application will fail if it's down) or soft (application will continue to work when it's down).
          example: hard
        status:
          $ref: '#/components/schemas/DependencyStatus'
tags:
  - name: Metrics
    description: Application metrics endpoints
  - name: Status
    description: Application status endpoints
  - name: Probes
    description: Application health probe endpoints
