skills.rest
michaelsvanbeek
michaelsvanbeekCOMMUNITY
Explore all skills by this author →
GitHub

api-design

Define REST API design patterns and contract standards for endpoints and OpenAPI documentation.

1|2|Updated Apr 9, 2026
Search Tags:#design#versioning#api#openapi#rest#error-handling#pagination
One-click install
npx skills add https://github.com/michaelsvanbeek/personal-agent-skills --skill api-design-michaelsvanbeek
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/michaelsvanbeek/personal-agent-skills/tree/main/skills/api-design
Command: npx skills add https://github.com/michaelsvanbeek/personal-agent-skills --skill api-design-michaelsvanbeek

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

REST API design often suffers from inconsistent naming, ambiguous error handling, and mismatched documentation. This skill provides a cohesive set of conventions to ensure uniform API design across endpoints and teams.

Core Features & Use Cases

  • Resource Naming Consistency: Use plural nouns for collections, consistent routing patterns, and kebab-case naming.
  • HTTP Methods & Status Codes: Clear guidance on GET/POST/PUT/PATCH/DELETE usage and appropriate status codes.
  • OpenAPI Documentation & Versioning: Standards for OpenAPI specs, versioning strategies, and error envelope definitions.

Quick Start

Draft a new API contract document following these conventions.

Frequently Asked Questions about api-design

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

FAQPage Schema
What are the best practices for REST API resource naming and routing?▼

REST API resource naming should use plural nouns for collections, kebab-case conventions, and consistent routing patterns to ensure endpoint uniformity and clear contracts across development teams.

How do I design a consistent error handling envelope for my API?▼

API error handling requires standardized error envelopes and appropriate HTTP status codes to provide clear, interoperable feedback for REST endpoint failures and data validation issues.

What should be included in OpenAPI documentation for a REST API?▼

OpenAPI documentation must define data schemas, endpoint specifications, pagination structures, and versioning strategies to meet interoperability guardrails and maintain accurate API contracts.

Which HTTP status codes should I use for GET, POST, PUT, PATCH, and DELETE methods?▼

HTTP methods GET, POST, PUT, PATCH, and DELETE require specific, appropriate status codes to maintain REST API consistency and accurately represent endpoint operation outcomes.

How do I implement versioning and pagination in an API contract?▼

API versioning and pagination are implemented through defined contract standards that specify routing patterns and data schemas, ensuring consistent data retrieval across endpoint versions.

Related Skills

Explore More Software Engineering Skills→
VeradelaCruzVeradelaCruz

api-design

Define API requirements and generate OpenAPI or GraphQL schemas.

Community
Intermediate
Dokkabei97Dokkabei97
2

api-first-design

Design API contracts with OpenAPI and GraphQL schemas.

Community
Intermediate
yuhle-qugyuhle-qug

rest-api-expert

Design REST APIs with HTTP semantics and OpenAPI documentation.

Community
Intermediate
nimadorostkarnimadorostkar
25

graphql

Design and optimize GraphQL schemas with DataLoader batching and query cost analysis.

Community
Advanced