- Home
- Skills
- APIs & Backend
- API Integration Architect — Reliable Connections
Works with the AI Agents you already use
API Integration Architect — Reliable Connections
Design secure, observable integrations with clear ownership, resilient retries, idempotency, and reconciliation.
$9.99
API Integration Architect — Reliable Connections
Example session with this skill installed
Design a reliable integration between a fictional payment provider and our order service. Requirements: a customer can pay for an order; provider webhooks may be duplicated or arrive out of order; a client timeout can occur after payment succeeds; network requests may be retried; our order database is authoritative for fulfillment status. We have no verified provider API docs yet, so do not invent endpoint names, signature schemes, quotas, or exact webhook fields.
Provide system authority map, proposed flow, data and state mapping, idempotency/retry design, webhook handling, reconciliation, failure matrix, security/privacy controls, observability, test plan, staged rollout, and provider facts that must be verified. Distinguish generic architecture recommendations from provider-specific unknowns.
- Read your context and instructions
- Compiled the api integration architect
Payment-to-Order Integration Blueprint
Evidence boundary: This is a generic proposal for a fictional provider. No provider docs, endpoints, signatures, event names, quotas, or production systems were supplied or inspected. Mark all provider-specific details
REQUIRES_PROVIDER_VERIFICATION.
Authority and data ownership
| Concern | Authority | Integration rule |
|---|---|---|
| Order and fulfillment status | Internal order service/database | Only the order service transitions fulfillment; payment events cannot directly mark an order shipped |
| Payment attempt/result | Payment provider for provider-side transaction state; internal payment ledger for our recorded view | Store provider transaction ID and normalized state with source timestamp and reconciliation metadata |
| Customer/tenant identity | Our authenticated identity service | Never trust tenant/customer IDs supplied only in an event payload |
| Event receipt | Durable integration inbox | Preserve provider event ID, received time, verification result, and processing status; minimize sensitive payload retention |
Proposed flow
- Order service creates a pending payment attempt with a stable internal attempt ID and associates it with the order and tenant.
- Payment adapter calls the verified provider API using an idempotency key derived from the durable attempt ID. Record request intent before sending so a timeout can be reconciled rather than blindly recreated.
- For an ambiguous timeout, query the provider using its documented lookup mechanism or wait for verified events; do not assume failure and do not create a second charge with a new key.
- Webhook edge verifies the provider's documented signature/timestamp scheme over the raw request bytes, enforces size/time limits, and writes a minimal event record to a durable inbox before returning the provider-required acknowledgement.
- A worker deduplicates by provider plus event ID, correlates to the internal attempt, validates tenant/order association, and applies an allowed state transition. Store provider event time and receipt time; reject or quarantine stale, contradictory, or unknown transitions.
- Notify the order service through an authenticated internal command/event. The order service rechecks ownership and state, then authorizes fulfillment only from its own transition rules.
- Periodic reconciliation compares recent unresolved attempts and ledger state using verified provider APIs/reports. Differences create an alert and repair workflow; never silently overwrite the internal order history.
State and retry policy
Use explicit states such as CREATED, PENDING, SUCCEEDED, FAILED, and REFUNDED only after mapping them to the provider's actual vocabulary. Make transitions monotonic where business rules allow; record refunds/chargebacks as separate financial events rather than erasing a successful charge. Retry transient network/5xx/429 responses with bounded exponential backoff, jitter, documented retry-after handling, and a deadline. Do not automatically retry permanent validation/auth failures. Use a durable outbox for internal notifications so a database commit and message publication cannot drift.
| Failure | Safe response |
|---|---|
| Client times out after provider may have charged | Reuse same idempotency key; reconcile/query before any new attempt |
| Duplicate webhook | Acknowledge after durable receipt; idempotent inbox processing prevents duplicate business effect |
| Events arrive out of order | Compare verified provider sequence/version/time if documented; fetch authoritative current state when ambiguous |
| Signature invalid | Reject and log minimal metadata; never process payload |
| Internal worker unavailable | Keep event durable, retry with backoff, alert on age/dead-letter threshold |
| Reconciliation mismatch | Quarantine for review or controlled repair with an audit trail |
Security, privacy, and observability
Keep provider secrets in a managed secret store and rotate them. Verify webhook authenticity before parsing trusted fields; use TLS, least-privilege credentials, tenant checks, replay protection, and separate test/live credentials. Do not log PAN, secret tokens, or unnecessary personal data. Track correlation IDs across order, attempt, provider transaction, webhook, inbox, and reconciliation. Monitor success/failure/ambiguous rates, duplicate and out-of-order events, webhook age, retry volume, 429s, unresolved attempts, reconciliation drift, and dead letters with actionable alerts.
Verification and rollout
Before implementation, obtain authoritative provider docs for idempotency semantics and key retention, event/signature format, retry/acknowledgement requirements, event ordering guarantees, lookup/report APIs, rate limits, API versions, and payment/refund states. Test duplicate deliveries, invalid signatures, stale/reordered events, timeout-after-commit, provider throttling/outage, worker restart, tenant mismatch, refunds, and reconciliation mismatch in a sandbox. Roll out behind a feature flag to a small cohort, compare provider and internal ledgers, alert on drift, document manual recovery, and keep a tested rollback path. Do not enable real charges until the provider-specific contract and operational controls are verified.
Connects securely to your tools. The creator never sees your data.
About this skill
API Integration Architect turns business connection requirements into reliable system designs. It supports REST/HTTP, GraphQL, RPC/gRPC, webhooks, event streams, queues, file/batch exchange, database-adjacent synchronization, SaaS, payment and identity providers, AI integrations, marketplaces, internal services, and partner APIs.
The agent maps each system's business responsibility, source of truth, authoritative fields, read/write authority, identifiers, tenant boundary, data sensitivity, and operational owner before proposing synchronization. It chooses a fit-for-purpose integration pattern and defines contracts, identity, authorization, validation, data mapping, consistency, error semantics, retries, idempotency, timeouts, rate/capacity handling, pagination, caching, asynchronous workflow, webhook verification, queues, dead-letter handling, and reconciliation.
It plans privacy-aware logging and payload minimization, observability, SLOs, alerts, cost, provider replacement boundaries, testing, migration, staged rollout, rollback, API versioning, deprecation, and operational runbooks. Deliverables can include sequence flows, schemas, mapping tables, failure matrices, test plans, and decision records. Webhooks are treated as notifications rather than unquestioned truth; retries are designed for duplicates, reordering, ambiguous timeouts, and partial failure.
The agent never invents provider endpoints, fields, quotas, SLAs, pricing, credentials, or current capabilities. Current provider-specific details must be checked against authoritative documentation when available; otherwise they are marked for verification. It does not connect to accounts, send live requests, process real payments, or change production systems without explicit authorization. Designs are proposals until validated with actual contracts, threat model, traffic, and operational constraints.
The design depends on accurate system-of-record ownership, provider documentation, data schemas, traffic, retention, and operational constraints. Provider behavior can change; authentication, webhook signatures, event ordering, retry windows, quotas, and idempotency semantics must be checked against current official sources. A design cannot guarantee delivery, exactly-once effects, payment outcomes, or compliance. Sandbox tests and production monitoring are still required. Provider-specific API fields and infrastructure choices remain unknown when source evidence is absent.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 1 month ago
Permissions
File Scopes
Read only user-authorized specifications, code, payload samples, and logs; sanitize secrets and personal data first. Use public official documentation for current provider details. Never transmit credentials, send payment requests, process live webhooks, modify production integrations, or run load/destructive tests without explicit authorization and an approved sandbox or target.