playbooks

home / skills / vudovn / antigravity-kit / api-patterns

api-patterns skill

/.agent/skills/api-patterns

This skill helps you choose the right API style and design consistent, scalable responses across REST, GraphQL, and tRPC.

npx playbooks add skill vudovn/antigravity-kit --skill api-patterns

Review the files below or copy the command above to add this skill to your agents.

Files (12)
SKILL.md
2.4 KB
---
name: api-patterns
description: API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.
allowed-tools: Read, Write, Edit, Glob, Grep
---

# API Patterns

> API design principles and decision-making for 2025.
> **Learn to THINK, not copy fixed patterns.**

## 🎯 Selective Reading Rule

**Read ONLY files relevant to the request!** Check the content map, find what you need.

---

## đź“‘ Content Map

| File | Description | When to Read |
|------|-------------|--------------|
| `api-style.md` | REST vs GraphQL vs tRPC decision tree | Choosing API type |
| `rest.md` | Resource naming, HTTP methods, status codes | Designing REST API |
| `response.md` | Envelope pattern, error format, pagination | Response structure |
| `graphql.md` | Schema design, when to use, security | Considering GraphQL |
| `trpc.md` | TypeScript monorepo, type safety | TS fullstack projects |
| `versioning.md` | URI/Header/Query versioning | API evolution planning |
| `auth.md` | JWT, OAuth, Passkey, API Keys | Auth pattern selection |
| `rate-limiting.md` | Token bucket, sliding window | API protection |
| `documentation.md` | OpenAPI/Swagger best practices | Documentation |
| `security-testing.md` | OWASP API Top 10, auth/authz testing | Security audits |

---

## đź”— Related Skills

| Need | Skill |
|------|-------|
| API implementation | `@[skills/backend-development]` |
| Data structure | `@[skills/database-design]` |
| Security details | `@[skills/security-hardening]` |

---

## âś… Decision Checklist

Before designing an API:

- [ ] **Asked user about API consumers?**
- [ ] **Chosen API style for THIS context?** (REST/GraphQL/tRPC)
- [ ] **Defined consistent response format?**
- [ ] **Planned versioning strategy?**
- [ ] **Considered authentication needs?**
- [ ] **Planned rate limiting?**
- [ ] **Documentation approach defined?**

---

## ❌ Anti-Patterns

**DON'T:**
- Default to REST for everything
- Use verbs in REST endpoints (/getUsers)
- Return inconsistent response formats
- Expose internal errors to clients
- Skip rate limiting

**DO:**
- Choose API style based on context
- Ask about client requirements
- Document thoroughly
- Use appropriate status codes

---

## Script

| Script | Purpose | Command |
|--------|---------|---------|
| `scripts/api_validator.py` | API endpoint validation | `python scripts/api_validator.py <project_path>` |

Overview

This skill teaches practical API design principles and decision-making for modern services. It helps choose between REST, GraphQL, and tRPC, and covers response formats, versioning, pagination, and related operational concerns. The focus is on thinking through trade-offs and applying patterns appropriately rather than copy-pasting templates.

How this skill works

It guides you through a decision flow that matches API style to consumer needs, team constraints, and deployment patterns. It inspects common concerns—naming, HTTP semantics, type safety, response envelopes, error handling, and versioning—and gives concrete recommendations. It also highlights anti-patterns and a checklist to validate design choices before implementation.

When to use it

  • Selecting an API style for a new product or microservice
  • Refining response formats and error contracts for client teams
  • Planning API versioning and migration strategies
  • Choosing pagination and filtering approaches for large datasets
  • Deciding auth, rate limiting, and security testing needs

Best practices

  • Base style choice on client needs and team expertise, not inertia
  • Use consistent response envelopes and clear error schemas across endpoints
  • Prefer nouns and resource-based routes in REST; avoid verbs in URLs
  • Adopt semantic HTTP status codes and standard pagination metadata
  • Plan versioning up front (URI/header/query) and document migration paths
  • Include rate limiting and basic security checks early in design

Example use cases

  • Choosing GraphQL for rich client-driven querying and reduced round trips
  • Picking tRPC in a TypeScript monorepo to leverage end-to-end typesafety
  • Designing REST endpoints with clear resource names and correct HTTP methods
  • Defining a stable versioning strategy for public APIs to support backward compatibility
  • Implementing consistent error envelopes and pagination for mobile clients

FAQ

When should I pick GraphQL over REST?

Choose GraphQL if clients need flexible queries, efficient bundling of related data, or when you cannot predict client data needs. Avoid it for simple CRUD APIs or when caching and predictable endpoints are priorities.

Is tRPC only for full TypeScript stacks?

tRPC shines in TypeScript monorepos because of runtime-free type safety; avoid it for polyglot clients or public APIs where language-agnostic contracts are required.

How do I handle breaking changes?

Use versioning (URI or header) and deprecation headers, document migration steps, and support old versions for a defined window. Prefer additive changes and non-breaking evolutions when possible.