skills.rest
sebafermanelli
sebafermanelliCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

sfermanelli-api-design

Design REST and GraphQL API contracts with validation and versioning.

1|Updated Mar 19, 2026
Search Tags:#design#api#validation#rest#graphql#contracts#dto
One-click install
npx skills add https://github.com/sebafermanelli/sfermanelli-skills --skill sfermanelli-api-design
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: sfermanelli-api-design
Source: https://github.com/sebafermanelli/sfermanelli-skills/tree/main/sfermanelli-api-design
Command: npx skills add https://github.com/sebafermanelli/sfermanelli-skills --skill sfermanelli-api-design

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Design clean, consistent, and secure APIs — REST endpoints, GraphQL schemas, internal service contracts, and DTOs. Use this skill when the user asks to design an API, create endpoints, define a schema, plan an API surface, or says things like "design the API", "what should the endpoint look like", "create the routes", "define the contract", "design the schema". Distinct from write-docs (which documents existing code) — this designs new API contracts from requirements.

Core Features & Use Cases

  • REST API design: endpoint naming, versioning, idempotency, and error handling.
  • DTOs and schemas: define input/output shapes, validation, and mappings.
  • Advanced patterns: CQRS, event contracts, and API versioning strategies for evolving surfaces.
  • Use Case: design a new public API surface for a feature, including endpoints, schemas, and contracts, before implementation begins.

Quick Start

Design the API surface for a new feature by outlining endpoints, schemas, and DTOs from the requirements.

Frequently Asked Questions about sfermanelli-api-design

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

FAQPage Schema
How do I design a REST API surface from requirements before implementation?▼

Design a REST API by defining endpoint naming, versioning, idempotency, and error handling. This skill generates intuitive contracts and DTO mappings from requirements, ensuring the API is consistent and hard to misuse before code begins.

What's the best way to define DTOs and validation layers for an API?▼

Define DTOs and schemas by specifying input and output shapes, validation rules, and mappings. This skill enforces robust validation layers and naming conventions to secure data transfer objects across the API lifecycle.

Can I design GraphQL schemas and internal service contracts using this approach?▼

Yes, you can design GraphQL schemas and internal service contracts. The skill applies consistent naming conventions, validation, and error handling to both REST endpoints and GraphQL schemas.

How do I handle API versioning and evolving API surfaces?▼

Handle API versioning by applying advanced patterns and versioning strategies for evolving surfaces. This skill plans versioning and robust error handling to ensure contracts remain stable and intuitive as features expand.

Does this skill support designing event contracts and CQRS patterns?▼

Yes, it supports designing advanced patterns including CQRS and event contracts. You can define internal service contracts and event schemas with consistent naming, validation, and DTO mappings.

When do I need API design instead of documentation for my endpoints?▼

You need API design when creating new endpoints, schemas, or contracts from requirements. This skill designs the API surface, whereas documentation tools only describe existing code after implementation.

Related Skills

Explore More Software Engineering Skills→
ibnuhalimmibnuhalimm

Architect

Gather project context and produce a detailed architecture plan.

Community
Advanced
giuseppe-trisciuogliogiuseppe-trisciuoglio
322

spring-boot-openapi-documentation

Generate OpenAPI 3.0 documentation and Swagger UI for Spring Boot 3.x applications.

Community
Advanced
HCMUTE-RTICHCMUTE-RTIC

full-stack-orchestration-full-stack-feature

Orchestrate full-stack feature development across backend, frontend, and infrastructure layers.

Official
Advanced
personamanagmentlayerpersonamanagmentlayer
41

openapi-expert

Design OpenAPI/Swagger specifications and generate client/server code.

Official
Advanced