skills.rest
deandum
deandumCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

api-design

Design versioned REST or RPC API surfaces with separated transport and domain logic.

3|1|Updated Feb 10, 2026
Search Tags:#design#versioning#api#validation#http#dto#grpc
One-click install
npx skills add https://github.com/deandum/claude-resources --skill api-design-deandum
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/deandum/claude-resources/tree/main/skills/core/api-design
Command: npx skills add https://github.com/deandum/claude-resources --skill api-design-deandum

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Designs robust API surfaces by decoupling transport from domain logic, enabling consistent, versioned, and testable interfaces.

Core Features & Use Cases

  • Define resources and routes with consistent naming across REST/gRPC.
  • Separate Request/Response DTOs from domain models to prevent leakage and promote stable schemas.
  • Plan validation, error handling, middleware, and versioning to ensure predictable APIs.
  • Use cases include designing new endpoints, auditing surfaces for consistency, and evolving APIs safely.

Quick Start

Describe a new HTTP endpoint with clear routes, DTO boundaries, and proper error handling.

Frequently Asked Questions about api-design

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

FAQPage Schema
How do I design clear and consistent REST or gRPC API endpoints?▼

Design clear API endpoints by separating transport from domain logic, defining resources, routes, and DTOs to ensure consistent, versioned, and testable interfaces. This approach prevents domain model leakage and promotes stable schemas.

What is the best way to separate DTOs from domain models in API design?▼

Separate DTOs from domain models by defining distinct Request and Response Data Transfer Objects for your endpoints. This prevents internal domain leakage, maintains stable API schemas, and decouples transport layers from core logic.

How do I plan validation and error handling for HTTP and gRPC APIs?▼

Plan validation and error handling by mapping domain errors to consistent HTTP or gRPC responses and applying structured validation rules to DTOs. This ensures predictable API behavior across transport surfaces.

Can I use a structured workflow to version my API surfaces safely?▼

You can safely evolve APIs by applying a structured workflow that defines resources, routes, DTOs, middleware, and server configuration with built-in versioning. This enables consistent versioned interfaces and safe API evolution.

Why do my API endpoints leak internal domain logic into the response?▼

API endpoints leak domain logic when transport and domain layers are coupled. Prevent this by defining strict Request and Response DTOs that separate transport schemas from internal models, ensuring stable and predictable API surfaces.

Related Skills

Explore More Software Engineering Skills→
baphledbaphled
1

service-layer

Design application services for business logic orchestration and transaction management.

Community
Intermediate
hashintelhashintel
35

tanstack-start

Scaffold TanStack Start routing, API routes, and AI integrations for React apps.

Official
Intermediate
MysMonMysMon
2

api-design

Design contract-first APIs with OpenAPI, GraphQL SDL, and Protobuf contracts.

Community
Advanced
PhauksPhauks

prompt-engineering

Design robust prompts and system prompts for Claude agents.

Community
Basic