⚙️ Backend Engineering · API Design

Make writes safe with idempotency keys

Accept retried mutations gracefully by keying operations so duplicates return the original result.

intermediate~30 minBackend EngineersAPI DevelopersPlatform Engineers

Steps

1Require an Idempotency-Key header on POST payments, orders, and signups
2Store key + request hash + response in a table with TTL cleanup
3On replay with same payload, return stored response with replayed flag
4On same key different payload, reject with 422 conflict
5Expire keys after 24-48h depending on client retry windows
6Load-test double-submit behavior before launch week

Common Pitfalls

▲Keying only by user ID, colliding legitimate new requests
▲Storing responses forever without TTL or encryption

Commands

Install with skills CLI

$ npx skills add aniruddhaadak80/skills --skill api-design-idempotency-keys

Install globally

$ npx skills add aniruddhaadak80/skills --skill api-design-idempotency-keys -g

Tags

#reliability#payments#api#backend-engineering#api-design

Install this skill

$ npx skills add aniruddhaadak80/skills --skill api-design-idempotency-keys -a opencode

SKILL.md

# Make writes safe with idempotency keys

> Accept retried mutations gracefully by keying operations so duplicates return the original result.

## When to Use This Skill

Accept retried mutations gracefully by keying operations so duplicates return the original result.

## Steps

1. Require an Idempotency-Key header on POST payments, orders, and signups
2. Store key + request hash + response in a table with TTL cleanup
3. On replay with same payload, return stored response with replayed flag
4. On same key different payload, reject with 422 conflict
5. Expire keys after 24-48h depending on client retry windows
6. Load-test double-submit behavior before launch week

## Common Pitfalls

- Keying only by user ID, colliding legitimate new requests
- Storing responses forever without TTL or encryption

View source on GitHub ↗

Design stable resource-oriented endpoints with deliberate error contracts and pagination.

⚙️ Backend Engineering·~30m

Open →

Model REST resources without leaking internals (gRPC services)foundation

Design stable resource-oriented endpoints with deliberate error contracts and pagination.

⚙️ Backend Engineering·~30m

Open →

Migrate API versions without breaking clientsadvanced

Run two versions in parallel, observe usage, and sunset safely with real telemetry.

⚙️ Backend Engineering·~40m

Open →