# ─────────────────────────────────────────────────────────────────────────────
# APIS — published interfaces BETWEEN components.
#
# Path:  content/orgs/<org>/apis/<api>.yaml
# Docs:  content/orgs/<org>/docs/api/<api>/
#
# Kept separate from the Component that implements it because the CONTRACT has
# its own lifecycle: consumers care when the interface changes, not when
# internals do. The Component declares `providesApis`; the catalog stitches
# `apiProvidedBy` back onto this entity.
#
# `spec.definition` is the machine-readable schema, rendered in the Definition
# tab. Inline it for small APIs, or use `$text:` to pull a file.
# ─────────────────────────────────────────────────────────────────────────────
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  annotations:
    backstage.io/managed-by-location: url:https://static-ai-stack.dc7.io/catalog/example-org/apis/sample-service-api.yaml
    backstage.io/techdocs-ref: url:https://static-ai-stack.dc7.io/catalog/
  name: sample-service-api
  title: Sample Service API
  description: Minimal OpenAPI definition exercising the API catalog and docs rendering.
spec:
  type: openapi
  lifecycle: production
  owner: group:default/platform-team
  system: sample-system
  definition: |
    openapi: 3.0.0
    info:
      title: Sample Service API
      version: 1.0.0
      description: Health and echo endpoints used by the ai-stack functional test suite.
    paths:
      /health:
        get:
          summary: Liveness probe
          responses:
            '200':
              description: Service is healthy
              content:
                application/json:
                  schema:
                    type: object
                    properties:
                      status: { type: string, example: ok }
      /echo:
        post:
          summary: Echo the request body back
          requestBody:
            required: true
            content:
              application/json:
                schema:
                  type: object
          responses:
            '200':
              description: The same payload