# Service API Patterns

> Use when building or reviewing an HTTP service's plumbing. Rate limiting, endpoint organization, validation, pagination and list queries, hardened cross-service HTTP calls, long-running work without a queue, background services versus migrations, seeded definitions, and the migration completion signal. Most are one extension method, which is why they belong in the shared kernel rather than copy-pasted per service.

- Skill: `konradcinkusz/service-api-patterns` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add konradcinkusz/service-api-patterns`
- Raw SKILL.md: https://api.skillmd.com/api/skills/konradcinkusz/service-api-patterns/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: konradcinkusz (https://skillmd.com/u/konradcinkusz)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/konradcinkusz/service-api-patterns

---


# Recurring service and API patterns

**Read [`references/SERVICE-API-PATTERNS.md`](references/SERVICE-API-PATTERNS.md) before applying any of this.**
That file is the standard; everything below it is a summary to help you decide
whether this skill applies and to check your work afterwards.

Reference-architecture principles: P2, P9.

## What this standard covers

- Rate limiting
- Endpoint organization
- Validation
- Pagination and list queries
- Cross-service HTTP calls
- Long-running work without a queue
- Background services vs migrations
- Seeded definitions
- Product mechanics worth reusing

## Checklist

- [ ] Rate limiting from the kernel: user-partitioned with IP fallback, `auth`/`api`/global policies, uniform 429 body
- [ ] Anonymous surfaces: one shared client resolver; the forwarded client header trusted only when configuration says a proxy is in front; rejections not queued; a process-wide concurrency bound underneath, with health probes exempt
- [ ] Endpoint groups make the three trust levels visible in the composition root; operation names from constants
- [ ] Validation filter (minimal APIs) / logging 400 factory (MVC); client mirrors marked, server authoritative
- [ ] Every list endpoint clamps page/limit; page aggregates in one round trip
- [ ] Service-to-service clients: no auto-redirect, 3xx → 502 + log, bearer forwarded, timeouts by criticality, handler timeouts explicit
- [ ] Writes: a refused connection and a timeout reported differently; no retry of an indeterminate write, ever; a client-supplied idempotency key where the callee supports one, and the weaker fallback labelled as weaker where it does not
- [ ] 202 jobs: own scope, inputs captured, catch-all → Failed, progress message; caveats and the queue trigger written down
- [ ] Relays queue onto a bounded channel with an explicit drop policy, pass raw bytes, enable by config presence, and drop deliberately after a bounded retry
- [ ] Background services await the migration completion signal
- [ ] Seeded definitions: insert-if-missing by slug, never overwrite
- [ ] Product mechanics above reused, not reinvented

---

Generated from [`docs/guides/SERVICE-API-PATTERNS.md`](https://github.com/konradcinkusz/architecture-standards/blob/main/docs/guides/SERVICE-API-PATTERNS.md) by `scripts/build-marketplace.mjs`. Do not edit this file: change the source document, or its entry in `catalog/marketplace.catalog.json`, and re-run the generator.