skills.rest
kennypallchizaca-coder
kennypallchizaca-coderCOMMUNITY
Explore all skills by this author →
GitHub

03-rest-api-design

Design REST API contracts with OpenAPI-compliant envelopes and versioning.

Updated Mar 9, 2026
Search Tags:#versioning#openapi#http#rest-api#contract-design#endpoint-design#statelessness
One-click install
npx skills add https://github.com/kennypallchizaca-coder/agentic-full-stack-skills --skill 03-rest-api-design
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: 03-rest-api-design
Source: https://github.com/kennypallchizaca-coder/agentic-full-stack-skills/tree/main/skills-backend/03-rest-api-design
Command: npx skills add https://github.com/kennypallchizaca-coder/agentic-full-stack-skills --skill 03-rest-api-design

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

REST APIs drift when explicit contracts are missing, leading to inconsistent routes, ambiguous status codes, and brittle client implementations. This skill defines resource-oriented HTTP contracts with predictable routes, status codes, envelopes, versioning, and OpenAPI discipline to keep teams aligned and integration predictable.

Core Features & Use Cases

  • Establish standardized collection and item routes with clear HTTP verb semantics, envelopes, and versioning.
  • Provide OpenAPI-ready contracts that reflect the implementation intent and enable automated client generation and validation.
  • Cover typical backend scenarios such as CRUD endpoints, nested resources, pagination, filtering, and public/internal API distinctions.

Quick Start

Define an HTTP contract for a resource by outlining endpoints, verbs, status codes, envelopes, and OpenAPI artifacts.

Frequently Asked Questions about 03-rest-api-design

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

FAQPage Schema
How do I design a REST API contract with consistent routes and OpenAPI compliance?▼

Design a REST API contract by defining resource-oriented HTTP endpoints, standardizing status codes and envelopes, and applying versioning to generate machine-readable OpenAPI artifacts for predictable client integration.

What is the best way to version REST API endpoints and maintain statelessness?▼

Version REST API endpoints by enforcing statelessness and selecting a consistent versioning strategy within your HTTP contracts, ensuring predictable client integration and proper HTTP semantics across typical backend architectures.

How do I structure CRUD endpoints for nested resources with pagination and filtering?▼

Structure CRUD endpoints for nested resources by defining collection and item routes with clear HTTP verb semantics, then apply consistent envelopes to handle pagination and filtering across your REST API.

How does standardizing REST API contracts prevent inconsistent routes and brittle clients?▼

Standardizing REST API contracts prevents inconsistent routes and brittle clients by enforcing statelessness, explicit versioning, proper HTTP semantics, and OpenAPI discipline to keep backend teams aligned and integration predictable.

Can I use this approach to define both public and internal API contracts?▼

Yes, you can define both public and internal API contracts using this approach, as it covers typical backend scenarios including CRUD endpoints, nested resources, and distinct public versus internal API contract definitions.

Why do my REST APIs drift and suffer from ambiguous HTTP status codes?▼

REST APIs drift and suffer from ambiguous HTTP status codes when explicit contracts are missing, which is resolved by establishing resource-oriented HTTP contracts with predictable routes and OpenAPI discipline.

Related Skills

Explore More Software Engineering Skills→
mikopbxmikopbx
569

openapi-analyzer

Extract and analyze OpenAPI 3.1.0 specifications to validate endpoints and generate tests.

Official
Advanced
ehtbantonehtbanton

openapi-spec-builder

Generate OpenAPI 3.x specification files in YAML or JSON format.

Community
Intermediate
bibektimilsina00bibektimilsina00
1

new-api-feature

Scaffold a layered FastAPI CRUD feature with SQLAlchemy models and Pydantic schemas.

Community
Advanced
erichowenserichowens
181

api-architect

Design and validate REST, GraphQL, and gRPC API contracts and architectures.

Community
Advanced