# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for debarchive Mirror Service API
  version: 1.0.0
extends: openapi/canonical-mirrorservice-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 8
- target: $.paths['/v1/mirrors'].get
  update:
    x-apievangelist-phrasing:
      intent: List package mirrors
      effect: read
      questions:
      - Which package mirrors have I set up?
      - Can I filter and page through my mirror list?
      instructions:
      - text: List my mirrors, {pageSize} per page.
        slots:
          pageSize: query.pageSize
      - text: List mirrors matching filter {filter}.
        slots:
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/mirrors'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a Debian archive mirror
      effect: write
      questions:
      - How do I set up a mirror of an upstream Debian or Ubuntu archive?
      - Does creating a mirror start downloading packages right away?
      - Can I include source packages or udebs in a new mirror?
      instructions:
      - text: Create mirror {displayName} of {archiveRoot} for distribution {distribution}, components {components}, architectures {architectures}.
        slots:
          displayName: requestBody.displayName
          archiveRoot: requestBody.archiveRoot
          distribution: requestBody.distribution
          components: requestBody.components
          architectures: requestBody.architectures
      - text: Create a mirror with ID {mirrorId} verified by GPG key {gpgKey}.
        slots:
          mirrorId: query.mirrorId
          gpgKey: requestBody.gpgKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/mirrors/{mirror}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a mirror's details
      effect: read
      questions:
      - When did a mirror last download from upstream?
      - How do I check the status of one mirror?
      instructions:
      - text: Show mirror {mirror}.
        slots:
          mirror: path.mirror
      - text: Get the last download date of mirror {mirror}.
        slots:
          mirror: path.mirror
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/mirrors/{mirror}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a mirror
      effect: destructive
      questions:
      - How do I remove a mirror I no longer need?
      - Can I force-delete a mirror that is still in use?
      instructions:
      - text: Delete mirror {mirror}.
        slots:
          mirror: path.mirror
      - text: 'Force the deletion of mirror {mirror}: {force}.'
        slots:
          mirror: path.mirror
          force: query.force
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/mirrors/{mirror}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change a mirror's upstream settings
      effect: write
      questions:
      - Can I add architectures or components to an existing mirror?
      - How do I update only specific fields of a mirror with an update mask?
      instructions:
      - text: Update mirror {mirror} to architectures {architectures}.
        slots:
          mirror: path.mirror
          architectures: requestBody.architectures
      - text: Patch fields {updateMask} on mirror {mirror}.
        slots:
          updateMask: query.updateMask
          mirror: path.mirror
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/mirrors/{mirror}/packages'].get
  update:
    x-apievangelist-phrasing:
      intent: List packages in a mirror
      effect: read
      questions:
      - Which packages are available in my mirror?
      - Can I page through the package list of a large mirror?
      instructions:
      - text: List the packages in mirror {mirror}.
        slots:
          mirror: path.mirror
      - text: Show {pageSize} packages from mirror {mirror}.
        slots:
          pageSize: query.pageSize
          mirror: path.mirror
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/mirrors/{mirror}:sync'].post
  update:
    x-apievangelist-phrasing:
      intent: Sync a mirror with its upstream
      effect: write
      questions:
      - How do I pull the latest packages into a mirror?
      - Can a sync skip packages already downloaded or ignore checksum errors?
      instructions:
      - text: Sync mirror {mirror} named {name}.
        slots:
          mirror: path.mirror
          name: requestBody.name
      - text: Force-update mirror {mirror} ({name}) using keyrings {keyrings}.
        slots:
          mirror: path.mirror
          name: requestBody.name
          keyrings: requestBody.keyrings
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/mirrors:batchGet'].post
  update:
    x-apievangelist-phrasing:
      intent: Look up several mirrors by name
      effect: read
      questions:
      - Can I fetch several mirrors in one request by name?
      - Will a batch mirror lookup return partial results if one is missing?
      instructions:
      - text: Get the mirrors named {names}.
        slots:
          names: requestBody.names
      - text: Batch look up mirrors {names}, allowing partial success.
        slots:
          names: requestBody.names
      method: generated
      generated: '2026-09-26'