openapi: 3.0.3
info:
  title: Shoehorn Entities API
  description: Entity CRUD operations, status, changelog, workloads, scorecards, and governance.
  version: 1.0.0

servers:
  - url: https://shoehorn.example.com/api/v1
    description: Production

paths:
  /entities:
    get:
      summary: List entities
      description: Returns a paginated list of catalog entities.
      tags: [Entities]
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 20, maximum: 100 }
        - name: cursor
          in: query
          schema: { type: string }
        - name: type
          in: query
          schema: { type: string, enum: [service, library, api, website, tool, infrastructure, platform, mobile-app, data-pipeline, ml-model, documentation] }
        - name: lifecycle
          in: query
          schema: { type: string, enum: [experimental, development, production, deprecated] }
        - name: owner
          in: query
          schema: { type: string }
        - name: tier
          in: query
          schema: { type: string, enum: [tier1, tier2, tier3, tier4] }
      responses:
        '200':
          description: Paginated list of entities
          content:
            application/json:
              schema:
                type: object
                properties:
                  entities:
                    type: array
                    items: { $ref: '#/components/schemas/Entity' }
                  pagination:
                    $ref: '#/components/schemas/Pagination'

  /entities/{id}:
    get:
      summary: Get entity by ID
      tags: [Entities]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Entity details
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Entity' }
        '404':
          description: Entity not found

    put:
      summary: Update entity
      tags: [Entities]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/EntityUpdate' }
      responses:
        '200':
          description: Updated entity

    delete:
      summary: Delete entity
      tags: [Entities]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '204':
          description: Entity deleted

  /entities/{id}/readme:
    get:
      summary: Get entity README
      tags: [Entities]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: README content
          content:
            application/json:
              schema:
                type: object
                properties:
                  content: { type: string }
                  format: { type: string, enum: [markdown, html] }

  /entities/{id}/manifest:
    get:
      summary: Get entity manifest
      tags: [Entities]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Entity manifest YAML

  /entities/{id}/changelog:
    get:
      summary: Get entity changelog
      tags: [Entities]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Changelog entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  entries:
                    type: array
                    items: { $ref: '#/components/schemas/ChangelogEntry' }

  /entities/{id}/status:
    get:
      summary: Get entity status
      tags: [Entities]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Entity health and status

  /entities/{id}/deployments:
    get:
      summary: Get entity deployments
      tags: [Entities]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Deployment history

  /entities/{id}/resources:
    get:
      summary: Get entity resources
      description: Returns associated cloud and infrastructure resources for an entity.
      tags: [Entities]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Associated resources

  /entities/{id}/k8s/workloads:
    get:
      summary: Get entity K8s workloads
      tags: [Entities]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Kubernetes workload instances
          content:
            application/json:
              schema:
                type: object
                properties:
                  instances:
                    type: array
                    items: { $ref: '#/components/schemas/WorkloadInstance' }

  /entities/{id}/quick-actions:
    get:
      summary: Get entity quick actions
      tags: [Entities]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Available quick actions

  /entities/{id}/scorecard:
    get:
      summary: Get entity scorecard
      tags: [Entities]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Scorecard results with grade and category scores

  /entities/{id}/governance/actions:
    get:
      summary: Get governance actions for entity
      tags: [Entities]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Governance actions targeting this entity

  /entities/{id}/zombies:
    get:
      summary: Get zombie workloads for entity
      tags: [Entities]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Zombie (unowned) workloads associated with entity

  /entities/{id}/activity:
    get:
      summary: Get entity activity feed
      tags: [Entities]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Activity timeline

  /entities/{id}/incidents:
    get:
      summary: Get entity incidents
      tags: [Entities]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Incidents associated with entity

  /entities/{id}/oncall:
    get:
      summary: Get entity on-call schedule
      tags: [Entities]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: On-call information

  /entities/{id}/relations:
    get:
      summary: Get entity relations
      tags: [Entities]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Entity dependency and relationship graph

  /entities/{id}/topology:
    get:
      summary: Get entity service topology
      tags: [Entities]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Network topology for entity

  /entities/{id}/docs:
    get:
      summary: Get entity documentation
      tags: [Entities]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Documentation entries for entity

  /entities/summary:
    get:
      summary: Get entities summary statistics
      tags: [Entities]
      responses:
        '200':
          description: Summary counts by type, lifecycle, tier

components:
  schemas:
    Entity:
      type: object
      properties:
        id: { type: string, format: uuid }
        service_id: { type: string, description: Human-readable identifier }
        name: { type: string }
        type: { type: string }
        lifecycle: { type: string }
        owner: { type: string }
        description: { type: string }
        tier: { type: string }
        tags: { type: array, items: { type: string } }
        links: { type: array, items: { $ref: '#/components/schemas/Link' } }
        source: { type: string, enum: [kubernetes, manifest, api, github, manual] }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    EntityUpdate:
      type: object
      properties:
        name: { type: string }
        description: { type: string }
        owner: { type: string }
        lifecycle: { type: string }
        tier: { type: string }
        tags: { type: array, items: { type: string } }

    Link:
      type: object
      properties:
        title: { type: string }
        url: { type: string, format: uri }
        icon: { type: string }

    ChangelogEntry:
      type: object
      properties:
        id: { type: string }
        timestamp: { type: string, format: date-time }
        action: { type: string }
        field: { type: string }
        old_value: { type: string }
        new_value: { type: string }
        actor: { type: string }

    WorkloadInstance:
      type: object
      properties:
        cluster_id: { type: string }
        namespace: { type: string }
        name: { type: string }
        kind: { type: string, enum: [Deployment, StatefulSet, DaemonSet, CronJob, Job] }
        replicas: { type: integer }
        ready_replicas: { type: integer }
        image: { type: string }
        last_seen: { type: string, format: date-time }

    Pagination:
      type: object
      properties:
        total: { type: integer }
        page: { type: integer }
        pageSize: { type: integer }
        nextCursor: { type: string }
