api-design

Design RESTful API contracts with endpoint specs, JSON Schema, and error codes.

Updated Apr 10, 2026
One-click install
npx skills add https://github.com/ramybarsoum/RStack-V0 --skill api-design-ramybarsoum
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/ramybarsoum/RStack-V0/tree/main/skill/api-design
Command: npx skills add https://github.com/ramybarsoum/RStack-V0 --skill api-design-ramybarsoum

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Designing consistent, machine-readable RESTful API contracts is time-consuming and error-prone, leaving engineering teams with ambiguous endpoints, inconsistent schemas, and unclear error handling. This Skill centralizes endpoint specifications, request and response schemas, versioning guidance, and authentication patterns into a single consumable design for developer handoff and implementation.

Core Features & Use Cases

  • Endpoint Specifications: Detailed route definitions with HTTP methods, path parameters, query parameters, and example payloads.
  • Schemas & Errors: JSON Schema request/response shapes, example bodies, and standardized error codes with handling recommendations.
  • Versioning & Auth: Clear versioning strategies and authentication patterns (e.g., bearer tokens, scopes) tailored to integration needs.
  • Use Case: Turn a product feature description like "CRUD for patient preferences" into a complete API contract ready for implementation and documentation.

Quick Start

Provide a concise feature description such as CRUD for patient preferences to generate endpoint specs, request/response schemas, error codes, and authentication patterns saved to work/api-designs.

Frequently Asked Questions about api-design

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

FAQPage Schema
How do I design a RESTful API with clear endpoint specs and JSON Schema definitions?

Design a RESTful API by generating route definitions, JSON Schema request and response examples, and standardized error codes. This approach handles HTTP methods, path parameters, and query parameters to produce a complete API contract ready for developer handoff.

What is the best way to define REST API authentication patterns and versioning strategies?

Defining REST API authentication and versioning involves specifying clear strategies like bearer tokens and scopes tailored to integration needs. This ensures consistent versioning and secure access control across endpoint specifications for backend services.

Can I generate a complete CRUD API contract from a feature description for backend services?

Yes, you can generate a complete CRUD API contract from a concise product feature description. The process outputs detailed endpoint specifications, example payloads, and error handling recommendations suitable for automated documentation.

How do I standardize error codes and handling recommendations in an OpenAPI or REST design?

Standardize error codes in a REST API design by defining standardized error responses alongside JSON Schema request and response shapes. This produces explicit error handling guidance for client integrations and developer handoff.

Do I need an existing OpenAPI specification to generate API endpoint definitions and schemas?

No, you do not need an existing OpenAPI specification. You can provide a concise feature description such as CRUD for patient preferences to generate endpoint specs, request and response schemas, and authentication patterns from scratch.

When should I not use an automated API design approach for integration endpoints?

Avoid automated API design when an integration endpoint requires highly custom non-RESTful protocols or complex real-time streaming schemas. This approach targets standard RESTful CRUD surfaces and may not fit specialized asynchronous messaging contracts.