CAST AI Contract-First API Adapter

Overview

Create a narrow adapter around approved CAST AI operations. Treat the OpenAPI description, regional base URL, organization scope, response schemas, and endpoint-specific rate behavior as explicit dependencies.

Prerequisites

• Named operations and business purpose
• CAST AI region, organization boundary, and least-privilege service identity
• Current OpenAPI contract pinned or checksummed for generation
• Error, retry, telemetry, and secret-handling policy

Instructions

Step 1: Choose API versus Terraform

Use Read and Grep to determine whether the work is declarative infrastructure or runtime integration. Prefer the supported Terraform provider for owned desired state; use REST for bounded runtime reads or operations that the chosen provider does not own.

Step 2: Pin the contract

Record the current API specification origin, retrieval time, checksum, selected operation IDs, and generated-client tool version. Do not copy guessed paths from examples or expose the entire generated surface to application code.

Step 3: Build the transport boundary

Use Write or Edit to implement injected regional base URL, X-API-Key header handling, optional enterprise organization header, request timeout, cancellation, bounded response size, structured redaction, and correlation metadata. Never place keys in URLs or exception messages.

Step 4: Normalize domain operations

Expose small intent-oriented methods with validated identifiers and typed results. Keep raw provider payloads behind the adapter, retain unknown fields safely, and distinguish absent data from zero values.

Step 5: Classify failures

Map transport failures, 401, 403, 404, 409, endpoint-specific 429, 5xx, schema mismatch, deadline exhaustion, and uncertain mutation outcome. Retry only proven idempotent operations within a shared request budget.

Step 6: Test without CAST AI

Add fixtures for every status class, regional mismatch, enterprise header omission, pagination, unknown fields, redaction, timeout, cancellation, and throttling. Keep an optional live smoke test read-only and separately protected.

Tool Discipline

Use Read and Grep for contract and repository discovery. Use Write and Edit for the adapter, fixtures, tests, and contract receipt. This skill does not fetch credentials, call production, or claim an unofficial library is vendor-supported.

Output

• API-versus-Terraform ownership decision
• Pinned contract receipt and selected operations
• Narrow authenticated adapter with normalized failures
• Offline contract suite and protected smoke-test boundary

Examples

A reporting service wraps two read operations and hides generated types behind its own domain model. The same repository leaves cluster policy desired state in Terraform to avoid competing authorities.

Error Handling

Failure	Response
OpenAPI operation changes	Fail generation or contract tests for review
Region and identity disagree	Stop before sending the request
Mutation result is uncertain	Reconcile state before retry
Response contains an unknown field	Preserve compatibility and log only its schema path

Resources

• Adapter evidence and source notes
• API access
• CAST AI API specification
• CAST AI API FAQ