REST Automation Skill

This skill enforces reliability and safety when building automations that call REST APIs.

When to use this skill

Use whenever the task involves:

• •calling external REST APIs (CRUD, search, sync)
• •integrating 2+ systems (ETL, iPaaS-like flows)
• •webhooks, polling, or scheduled jobs
• •data ingestion, normalization, enrichment, deduplication

Default design principles

• •Idempotent by design: repeats should not create duplicates or corrupt data.
• •Observable: logs/metrics correlate each run and each API call.
• •Fail safe: handle partial failures; avoid silent data loss.
• •Rate-limit aware: backoff and respect vendor limits.
• •Least privilege: handle secrets safely, avoid overbroad scopes.

Checklist (apply unless irrelevant)

1) Define the contract

• •Inputs (format, required fields, validation)
• •Outputs (where data goes, expected shape)
• •Success criteria (what “done” means)
• •Non-goals (what the automation will not do)

2) Authentication & secrets

• •Identify auth type: API key, OAuth2, JWT, mTLS
• •Never hardcode secrets in code or logs
• •Support secret injection via env vars / secret manager
• •Plan token refresh if applicable (OAuth2)

3) Idempotency & deduplication

Pick at least one:

• •Use provider idempotency keys (if supported)
• •Use stable external IDs (e.g., external_id field) for upserts
• •Keep a local/state store mapping source IDs -> target IDs
• •Use deterministic hashes for dedupe when no stable ID exists Document the idempotency strategy explicitly.

4) Pagination & incremental sync

• •Detect pagination style: next link, cursor, page+limit, offset+limit
• •Ensure loops terminate safely (max pages / max time)
• •Prefer incremental sync using updated_since/ETag/If-Modified-Since when possible
• •Handle out-of-order updates and late-arriving events

5) Retries, backoff, and timeouts

• •Set timeouts for connect/read
• •Retry on transient errors: network failures, 429, 5xx (with limits)
• •Use exponential backoff with jitter if possible
• •Do not retry on most 4xx (except 408/409/429 depending on semantics)
• •Cap retries and surface failures clearly

6) Rate limits & quotas

• •Respect Retry-After and rate-limit headers
• •Implement adaptive backoff on 429
• •Consider batch endpoints to reduce call volume
• •Avoid bursty concurrency unless explicitly safe

7) Data mapping & validation

• •Explicit mapping layer (source -> normalized -> target)
• •Validate required fields and types
• •Normalize common formats (dates, enums, currency, locales)
• •Handle nullability and partial payloads
• •Record rejected records with reasons (don’t silently drop)

8) Error handling strategy

Choose and document per error class:

• •Skip with log (non-critical record)
• •Retry (transient)
• •Quarantine (store failing payload for later)
• •Fail the run (systemic issue) Ensure the workflow reports a clear summary at the end.

9) Observability & audit trail

Minimum:

• •Run ID / correlation ID
• •Per-request logs: method, path (not full secrets), status, latency, attempt count
• •Counters: processed, created, updated, skipped, failed Prefer structured logs (JSON) if possible.

10) Webhooks (if involved)

• •Verify signature (if provided)
• •Handle replay (idempotency for event IDs)
• •Respond quickly; process async if needed
• •Store raw event payloads (optional but recommended)

11) Safety controls

• •Dry-run mode (no writes)
• •Limit scope (max records per run)
• •“Kill switch” config flag
• •Backups/rollback plan for destructive operations

Output requirements (when producing a solution)

Include:

• •Idempotency strategy (1–3 bullets)
• •Retry/backoff policy
• •Pagination/incremental sync approach (if relevant)
• •Error handling strategy + what gets logged/quarantined
• •Verification plan (tests or a safe sandbox run plan)