api-design

Defines REST, tRPC, and GraphQL API conventions including pagination, versioning, errors, and webhooks.

1|Updated Aug 17, 2026
One-click install
npx skills add https://github.com/NalinDalal/skillset --skill api-design-nalindalal
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/NalinDalal/skillset/tree/main/skills/backend/api-design
Command: npx skills add https://github.com/NalinDalal/skillset --skill api-design-nalindalal

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams building APIs often end up with inconsistent URL structures, ad-hoc error formats, missing pagination, and unclear versioning rules, which makes APIs hard to consume and maintain. ## Core Features & Use Cases - Paradigm Selection Guidance: Compares REST, tRPC, and GraphQL with concrete trade-offs so you pick the right approach for public APIs, internal TypeScript monorepos, or complex client queries. - Standardized Conventions: Provides URL structure, HTTP status codes, success/error response envelopes, cursor and offset pagination, filtering/sorting syntax, and deprecation policy. - Implementation Patterns: Includes tRPC router/middleware examples, OpenAPI schema generation, webhook delivery with HMAC signature verification, and per-endpoint rate limiting. - Use Case: When designing a new projects API, load this skill to get a complete checklist covering validation, idempotency keys, caching headers, and audit logs before writing any endpoint code. ## Quick Start Ask the agent to design a versioned REST API for a projects resource with cursor pagination, standardized error responses, and webhook support.

Frequently Asked Questions about api-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I choose between REST, tRPC, and GraphQL for my API?▼

Use REST for public APIs, webhooks, and simple CRUD with caching needs. Choose tRPC for TypeScript monorepos needing end-to-end type safety on internal APIs. Pick GraphQL when clients require complex, flexible queries across federated data sources.

What is the best pagination approach for a REST API?▼

Cursor-based pagination is preferred for large datasets because it stays consistent as records change. Offset-based pagination with page and limit parameters works for small, relatively static datasets where total counts matter.

How do I version a REST API without breaking existing clients?▼

Use URL versioning like /api/v1/ and support the previous version for at least 12 months. Send Deprecation and Sunset headers on old endpoints and communicate removal six months in advance.

How do I secure incoming webhooks with signature verification?▼

Verify webhooks by computing an HMAC-SHA256 of the raw request body with a shared secret and comparing it to the signature header. Reject requests with mismatched signatures using a 401 response before processing the payload.

What should a standardized API error response include?▼

An error response should include a machine-readable code like VALIDATION_ERROR, a human-readable message, field-level details for validation failures, and a requestId for tracing. Map codes to consistent HTTP statuses such as 400, 401, 404, and 429.