API Evangelist enhancements — Azure Batch data plane (2025-06-01)

overlay: 1.0.0
info:
  title: API Evangelist enhancements — Azure Batch data plane (2025-06-01)
  version: 1.0.0
extends: openapi/_original/microsoft-azure-batch-batch-service-openapi.json
x-generated: '2026-09-17'
x-method: generated
x-source: openapi/_original/microsoft-azure-batch-batch-service-openapi.json
x-note: Captures API Evangelist annotations on top of the provider contract WITHOUT mutating it. Every
  fact asserted here is sourced from an artifact in this repository or from a Microsoft-published page
  named in the action description.
actions:
- target: $.info
  description: Record provenance and the artifacts derived from this contract.
  update:
    x-apievangelist:
      profile: https://apis.io/microsoft-azure-batch
      harvested: '2026-09-17'
      harvested_from: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/batch
      artifacts:
        errors: errors/microsoft-azure-batch-error-codes.yml
        conventions: conventions/microsoft-azure-batch-conventions.yml
        authentication: authentication/microsoft-azure-batch-authentication.yml
        scopes: scopes/microsoft-azure-batch-scopes.yml
        lifecycle: lifecycle/microsoft-azure-batch-lifecycle.yml
        rate_limits: rate-limits/microsoft-azure-batch-rate-limits.yml
        data_model: data-model/microsoft-azure-batch-data-model.yml
- target: $.info
  description: State the error envelope, which the contract models only as a default response.
  update:
    x-error-envelope:
      format: azure-batch-error-envelope
      rfc9457: false
      media_type: application/json
      shape: '{ code, message: { lang, value }, values: [ { key, value } ] }'
      published_codes: 125
      reference: https://learn.microsoft.com/en-us/rest/api/batchservice/batch-status-and-error-codes
- target: $.paths..[?(@.operationId)]
  description: Mark that every data-plane operation requires the api-version query parameter and accepts
    client-request-id / return-client-request-id correlation headers.
  update:
    x-runtime-conventions:
      api_version_required: true
      current_api_version: '2025-06-01'
      correlation_headers:
      - client-request-id
      - return-client-request-id
      timestamp_header: ocp-date
- target: $.paths./jobs/{jobId}.delete
  description: Flag the irreversible write surface. Recorded in conventions/ reversibility[].
  update:
    x-reversibility:
      reversible: false
      reversal: null
      note: Permanent; cascades to the job’s tasks. Long-running (202) with no documented cancel.
- target: $.paths./pools/{poolId}.delete
  description: Flag the irreversible write surface.
  update:
    x-reversibility:
      reversible: false
      reversal: null
      note: Permanent; destroys every compute node in the pool and any data on them.
- target: $.paths./jobs/{jobId}/tasks/{taskId}/terminate.post
  description: Record the published reversal path and its window.
  update:
    x-reversibility:
      reversible: true
      reversal: Tasks_ReactivateTask
      window: Within the task retention period (7 days by default, if the node still exists) and inside
        the 180-day maximum task lifetime.
      source: https://learn.microsoft.com/en-us/azure/batch/batch-quota-limit#other-limits
- target: $.paths./pools/{poolId}/resize.post
  description: Record the published reversal path and its window.
  update:
    x-reversibility:
      reversible: partial
      reversal: Pools_StopPoolResize
      window: Only while the pool state is `resizing`.
- target: $.paths./pools/{poolId}/evaluateautoscale.post
  description: Mark the one rehearsal-safe operation in the contract.
  update:
    x-dry-run:
      is_dry_run: true
      note: Evaluates an autoscale formula against the pool and returns the result without applying it.