API + External Integrations
Sets boundaries for external API credentials, timeouts, retries, response validation, and failure handling.
Scenario
You maintain a production API that integrates with several external services.
Examples include:
- payment providers;
- email providers;
- CRM systems;
- webhook consumers;
- third-party APIs.
External systems introduce failure modes outside your application's control:
timeouts
rate limits
duplicate requests
partial failures
API version changes
temporary outages
You want agents to preserve reliability patterns when modifying integrations.
Repository Structure
integration-api/
├── src/
│ ├── api/
│ ├── integrations/
│ │ ├── payments/
│ │ │ ├── client.ts
│ │ │ ├── service.ts
│ │ │ └── webhook.ts
│ │ ├── email/
│ │ └── crm/
│ ├── jobs/
│ └── config/
├── tests/
│ ├── integration/
│ └── contracts/
├── package.json
└── AGENTS.md
AGENTS.md
# Integration Service Instructions
## External Services
- Keep third-party API logic inside the existing integration modules.
- Do not scatter provider-specific requests throughout feature code.
- Use the repository's existing HTTP clients and configuration.
## Credentials
- Load provider credentials through the existing server configuration.
- Never expose provider secrets to clients.
- Never log API keys, access tokens, signing secrets, or complete authorization headers.
## Timeouts and Failures
- Preserve existing timeout and retry behavior.
- Do not introduce unlimited retries.
- Distinguish transient failures from permanent failures where the integration architecture supports it.
## Idempotency
- Preserve existing idempotency mechanisms for operations that may be repeated.
- Use provider idempotency features when the repository already relies on them.
- Do not assume network failure means the provider did not process the request.
## Webhooks
- Verify webhook authenticity using the provider's established verification mechanism.
- Do not trust webhook payloads before verification.
- Handle duplicate webhook delivery safely where applicable.
- Preserve event identifiers used for deduplication.
## API Contracts
- Treat provider request and response formats as external contracts.
- Isolate provider-specific data models from core domain logic when the existing architecture does so.
- Handle unsupported or unexpected responses through established error paths.
## Testing
- Do not call production third-party services from automated tests.
- Use existing mocks, fixtures, contract tests, or sandbox environments.
- Test important success and failure paths.
- Test repeated delivery or execution where idempotency matters.
## Validation
For integration changes:
- run relevant unit/integration tests;
- run `pnpm lint`;
- run `pnpm typecheck`;
- verify configuration changes;
- review retry, timeout, and idempotency behavior.
What This Does
This creates a boundary between:
application domain
and:
external provider
For example:
Order Service
↓
Payment Integration
↓
Payment Provider
The order service should not need to know every provider-specific request field.
The integration layer can translate between application concepts and external API contracts.
What This Does NOT Do
The instructions do not hide all provider behavior behind meaningless abstractions.
Provider-specific behavior sometimes matters.
For example:
payment intent
webhook signature
idempotency key
provider event ID
may be essential concepts.
The goal is controlled integration, not pretending all providers are identical.
The file also does not encourage automatic retries for every failure.
Some operations are unsafe to repeat without idempotency.
Why These Instructions Matter
Distributed systems create ambiguity.
Suppose the application sends:
Charge customer ₹1,000
to a payment provider.
The connection times out.
The application does not know whether:
A. provider never received request
B. provider received but did not process request
C. provider successfully charged customer but response was lost
Blindly retrying can create duplicate charges.
This is why idempotency matters.
Webhook delivery has a similar property.
A provider may send the same event more than once.
A handler that assumes:
one event
=
one execution
can duplicate side effects.
Key Decisions
Isolate provider-specific behavior
Integration modules provide a clear location for external contracts.
Treat network outcomes as uncertain
A timeout is not proof that nothing happened.
Design retries with idempotency
Retry policy and idempotency strategy should be considered together.
Verify webhooks before trusting them
A webhook endpoint is externally reachable.
Payload authenticity should be established before processing trusted actions.
Expect duplicate delivery
Webhook and queue systems often provide at-least-once behavior rather than exactly-once execution.
Keep secrets server-side
Integration credentials should never become frontend configuration.
When to Use This Pattern
Use this pattern when:
- the application depends on external APIs;
- payments or other high-impact operations occur;
- webhooks are received;
- retries are possible;
- external outages must be handled;
- provider contracts can evolve.
The central principle is:
external integrations are unreliable boundaries, so reliability and security behavior must be part of their design.