# API Patterns

> ---

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

---

---
name: api-patterns
description: ALWAYS use this when the task involves API shape, contracts, auth, versioning, response structure, error handling, or service boundary design.
---

# API Patterns

## Selective Reading Rule

Start with:

- `references/usage-routing.md`
- `references/quality-checklist.md`

Then load only the inherited docs, scripts, assets, or examples that match the user's actual task.

## Selective Reading Rule

Start with:

- `references/senior-master-standard.md`


Start with the file that answers the current design question:

- `references/contract-playbook.md` for senior-level contract design and review
- `references/api-review-checklist.md` for final review before implementation
- `api-style.md` for REST vs GraphQL vs tRPC
- `rest.md` for REST endpoint and resource design
- `graphql.md` for GraphQL fit and schema considerations
- `trpc.md` for TypeScript-first monorepo APIs
- `response.md` for envelopes, pagination, and error contracts
- `versioning.md` for API evolution
- `auth.md` for authentication and caller identity
- `rate-limiting.md` for abuse protection
- `documentation.md` for API docs and discoverability
- `security-testing.md` when reviewing API risk

## Purpose

Choose an API style that fits the consumers, the team, and the product boundary.

An API is a contract. Changing it later is expensive, so design for clarity and operational reality early.

## Use This Skill When

- picking between REST, GraphQL, and tRPC
- shaping new endpoints or procedures
- normalizing responses, errors, pagination, or filtering
- deciding auth and versioning strategy
- reviewing whether an API is too leaky, inconsistent, or hard to evolve

## Core Workflow

1. Identify the consumers.
   - web client, mobile app, internal service, public integrators, same-repo frontend
2. Choose the transport and contract style.
   - REST, GraphQL, or tRPC based on usage patterns and team reality
3. Define resource or procedure boundaries.
4. Standardize responses.
   - success shape, errors, pagination, identifiers, timestamps
5. Decide control concerns.
   - auth, rate limiting, idempotency, versioning, observability
6. Document the contract in a way implementation can follow.

## Heuristics

- Use REST when resources and cacheable operations dominate.
- Use GraphQL when the client truly needs flexible graph traversal and multiple consumer views.
- Use tRPC when TypeScript-first internal velocity matters more than public portability.
- Keep error shapes consistent across the surface.
- Avoid exposing internal storage structure as public API design.

## Review Questions

- Can a new consumer understand the contract quickly?
- Are identifiers, status codes, and error shapes consistent?
- Is pagination stable and predictable?
- Can the API evolve without breaking common callers?
- Are auth and authorization boundaries obvious?

## Related Skills

- `architecture` for broader system-boundary decisions
- `database-design` when endpoint shape is being distorted by schema issues
- `mcp-builder` when the API surface is being adapted for tool-based LLM use
- `verification-before-completion` before claiming an API contract is ready