skills.rest
Fenntasy
FenntasyCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

api-design

Design REST APIs with resource modeling, HTTP semantics, and OpenAPI standards.

Updated May 9, 2020
Search Tags:#versioning#openapi#rest#error-handling#api-design#http-semantics
One-click install
npx skills add https://github.com/Fenntasy/dotfiles --skill api-design-fenntasy
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/Fenntasy/dotfiles/tree/main/claude/skills/api-design
Command: npx skills add https://github.com/Fenntasy/dotfiles --skill api-design-fenntasy

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Language-agnostic REST API design guidance to help teams craft robust, consistent, and scalable APIs following established standards.

Core Features & Use Cases

  • Resource-oriented design and URL structure
  • HTTP method semantics, status codes, RFC 9457 error format
  • Versioning, deprecation, pagination, filtering, authentication, authorization, security headers, caching
  • Use cases: designing new endpoints, auditing contracts, and guiding OpenAPI schemas

Quick Start

Apply these REST API design principles to your next endpoint review to ensure consistency and quality.

Frequently Asked Questions about api-design

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

FAQPage Schema
What is the best way to design REST API resource models and URL structures?▼

REST API resource modeling involves applying language-agnostic principles to structure URLs around nouns. Using resource-oriented design ensures scalable endpoints, consistent HTTP semantics, and clear API contracts across development teams.

How do I handle REST API error handling with consistent status codes?▼

REST API error handling should enforce RFC 9457 error formats and consistent HTTP status codes. This standardized approach returns machine-readable error details, ensuring robust API contracts and predictable developer experiences.

How does API versioning work when evolving REST endpoints?▼

API versioning provides a clear evolution path for REST endpoints without breaking existing clients. It involves applying language-agnostic guidance to manage deprecation, ensuring scalable API growth and backward compatibility.

Can I use OpenAPI standards for auditing existing REST API contracts?▼

OpenAPI standards are highly effective for auditing existing REST API contracts. Applying these design principles to endpoint reviews validates resource design, pagination, filtering, and security headers for consistency and quality.

Do I need authentication and security headers for internal REST APIs?▼

Authentication, authorization, and security headers are essential for robust REST APIs at every scale. Including them in resource design protects endpoints and enforces consistent access control across all internal and external API contracts.

What are the limitations of language-agnostic REST API design?▼

Language-agnostic REST API design provides structural guidance for HTTP semantics and OpenAPI schemas but does not generate framework-specific code. It guides contracts and endpoint reviews manually without automating implementation.

Related Skills

Explore More Software Engineering Skills→
musujmusuj

phase-1-schema

Define project terminology, entities, relationships, and data structures.

Community
Intermediate
monobaselabsmonobaselabs

typespec

Develop TypeSpec API definitions and generate OpenAPI specs, TypeScript types, validators, routes, and handler stubs.

Official
Advanced
hpsgdhpsgd

api-design

Design RESTful API contracts with resource models, HTTP methods, and error handling.

Official
Advanced
efekrbasefekrbas
41

api-design-principles

Design REST and GraphQL API contracts with typed schemas and consistent status codes.

Community
Advanced