# Third-Party API Build Brief Generator

Turn a desired external integration into a scoped implementation brief covering contracts, secrets, retries, idempotency, limits, and fallback behavior.

## Prompt

You are an integration architect who specializes in safe, maintainable third-party API connections for AI-assisted app development.

Inputs:
1. App workflow and integration goal: {{integration_goal}}
2. External service, API version, and documentation excerpts: {{api_context}}
3. Required data, events, and actions: {{data_and_actions}}
4. Authentication, webhook, rate-limit, and sandbox details: {{provider_constraints}}
5. Privacy, reliability, cost, and deployment constraints: {{app_constraints}}

Do the following:
1. Map the end-to-end integration flow, including trigger, request, response, persistence, user feedback, asynchronous events, and downstream side effects.
2. Define request and response contracts, field mappings, validation, source of truth, versioning, pagination, time zones, and handling for missing or unexpected values.
3. Specify secret storage, least-privilege credentials, webhook verification, replay protection, idempotency, timeout, bounded retry, backoff, rate-limit, and duplicate-event behavior.
4. Design loading, delayed, partial-success, provider-error, disconnected, and degraded-mode experiences, including which actions remain available during an outage.
5. Produce a build sequence, endpoint table, data mapping, environment checklist, test fixtures, failure matrix, observability events, and rollback plan. Label all provider behavior that requires confirmation from current official documentation.

## Best for

Vibe coders connecting an app to payments, email, calendars, CRMs, maps, or other external services without overlooking failure behavior.

## Compatible tools

- Claude
- ChatGPT

## How to use

- Attach relevant documentation excerpts and versions.
- Describe the complete user workflow around the API.
- State the source of truth for every shared field.
- Include outage and duplicate-event expectations.

## Customization tips

- Keep provider credentials on the server.
- Use idempotency keys for external writes.
- Test webhooks with recorded fixtures.
- Define a useful degraded mode before implementation.

## Example input

Goal: Add calendar booking to a tutoring marketplace. Service: Cal.com API and webhooks. Actions: show tutor availability, create a booking after payment succeeds, cancel when a refund is approved, and update the local booking record. Constraints: tutors connect their own accounts, webhook events may be duplicated, all times display in the learner’s zone, API secrets stay server-side, and checkout must degrade gracefully if availability cannot load.

## Example output

The brief maps payment success to an idempotent booking command and treats the provider as the schedule source while the app stores synchronized status and provider IDs. It defines timezone conversion boundaries, OAuth token storage, signed webhook verification, duplicate suppression, bounded retries, and a pending-confirmation state. If availability fails, users can request a callback rather than completing an uncertain booking. Fixtures cover duplicate webhooks, stale slots, refunds, and provider timeouts.