How do I choose between REST, GraphQL, and tRPC?

Evaluate data needs, client capabilities, and type-safety requirements against the api-patterns guidance (api-style.md, graphql.md, trpc.md) and use the decision checklist.

Should I version APIs if I use REST or GraphQL?

Yes. Plan a versioning strategy (versioning.md) and maintain a consistent response format (response.md) to prevent breaking clients.

How can I ensure security and reliability in my API design?

Incorporate auth patterns (auth.md), rate-limiting (rate-limiting.md), and security testing (security-testing.md); follow documented practices and run security audits per the guidance.

api-patterns

npx machina-cli add skill vudovn/antigravity-kit/api-patterns --openclaw

Files (1)

SKILL.md

2.4 KB

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>`

Source

git clone https://github.com/vudovn/antigravity-kit/blob/main/.agent/skills/api-patterns/SKILL.mdView on GitHub

Overview

This skill guides you through choosing the right API pattern (REST, GraphQL, or tRPC) and applying consistent response formats, versioning, and pagination. It emphasizes context-driven decisions over fixed patterns and aligns with the 2025 guidance in the content map and decision checklist.

How This Skill Works

Analyze project context using the content map (api-style.md, rest.md, graphql.md, trpc.md, versioning.md, response.md) to select an API style. Apply a consistent response envelope, plan versioning, and design pagination before implementation, then document and validate with standard tooling.

When to Use It

Building a public REST API with stable resources and broad client compatibility.
Need flexible queries and precise data retrieval to minimize over-fetching (GraphQL).
Working in a TypeScript monorepo and requiring end-to-end type safety (tRPC).
You must implement a clear versioning strategy and consistent response formats.
You need to enforce authentication, rate limiting, and security testing as part of API design.

Quick Start

Step 1: Scan the Content Map and decide REST, GraphQL, or tRPC based on your context.
Step 2: Define a consistent response format, pagination approach, and versioning plan.
Step 3: Implement the chosen pattern, document it (OpenAPI/Swagger), and validate with the API validator.

Best Practices

Start with a context-driven decision checklist before designing the API.
Define a consistent response format and pagination strategy (response.md).
Choose the API style based on context rather than defaulting to REST.
Document thoroughly using OpenAPI/Swagger where appropriate.
Plan versioning and authentication early and align with security considerations.

Example Use Cases

A public e-commerce REST API that uses standard HTTP methods and status codes with a clear envelope for errors.
A data-heavy admin dashboard using GraphQL to fetch only the needed fields for each page.
A TS fullstack project in a monorepo leveraging tRPC for end-to-end type safety between client and server.
An API with URI-based versioning and a documented versioning strategy.
An API implementing a consistent envelope pattern with pagination and centralized error handling.

Frequently Asked Questions

Add this skill to your agents