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 |