skills.rest
xotong
xotongCOMMUNITY
Explore all skills by this author →
GitHub

api-design-principles

Enforce REST and GraphQL API design conventions during development and reviews.

2|Updated May 8, 2026
Search Tags:#versioning#rest#graphql#error-handling#naming-conventions#api-design#http-status-codes
One-click install
npx skills add https://github.com/xotong/claude-marketplace --skill api-design-principles-xotong
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/xotong/claude-marketplace/tree/main/plugins/code-quality/skills/api-design-principles
Command: npx skills add https://github.com/xotong/claude-marketplace --skill api-design-principles-xotong

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

REST and GraphQL API design often suffers from inconsistent conventions, unclear versioning, and poor error handling. This Skill enforces naming conventions, HTTP semantics, status codes, versioning, pagination, RFC 7807 error format, and security headers during API design and review.

Core Features & Use Cases

  • Enforces REST conventions: resource naming (plural nouns, kebab-case), avoidance of verbs in URLs, and shallow nesting.
  • Validates HTTP methods, status codes, and RFC 7807 error responses for all endpoints.
  • Guides API versioning, paging strategies, and security headers to ensure backward compatibility and secure designs.
  • Use Case: When drafting a new endpoint, apply these principles to ensure clean, production-ready APIs.

Quick Start

Design an API endpoint that adheres to the above REST/GraphQL conventions.

Frequently Asked Questions about api-design-principles

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

FAQPage Schema
What are the standard REST API naming conventions and HTTP status codes for endpoint design?▼

REST API design requires resource naming using plural nouns and kebab-case, avoiding verbs in URLs, and applying shallow nesting. It also enforces correct HTTP methods and status codes to ensure clear, production-ready endpoints.

How do I format API error handling using RFC 7807?▼

API error handling using RFC 7807 provides a standardized problem details format for HTTP APIs. It enforces consistent error responses across REST and GraphQL services, preventing sensitive data leakage while returning actionable error details.

What is the best way to version REST APIs and implement pagination?▼

API versioning and pagination strategies ensure backward compatibility and manage large datasets. Applying proper versioning during API design prevents breaking changes, while pagination controls data payload sizes for secure, efficient services.

Does this approach enforce security headers for GraphQL and REST services?▼

Yes, auditing REST and GraphQL services enforces security headers to prevent sensitive data leakage. It validates that all endpoints include necessary security configurations during both new API design and existing service reviews.

When should I use GraphQL instead of REST for API development?▼

GraphQL and REST API design principles apply to different architectural needs. This approach audits both service types for naming conventions, error handling, and security, ensuring robust endpoints regardless of the chosen protocol.

How do I avoid verbs in URLs and structure REST resource naming correctly?▼

REST resource naming enforces plural nouns and kebab-case while avoiding verbs in URLs. It applies shallow nesting to maintain clear, standardized endpoint paths during API development and architectural reviews.

Related Skills

Explore More Software Engineering Skills→
takemo101takemo101

basic-design-writer

Generate foundational system design documents in Japanese with Mermaid diagrams.

Community
Intermediate
dinoudondinoudon

api-documentation

Generates API references and SDK scaffolds from OpenAPI specifications.

Community
Advanced
cenjiecenjie

api-security-hardening

Secure REST APIs with authentication, rate limiting, CORS, and input validation.

Community
Advanced
KILWA73KILWA73

api-contract-tester

Validates backend responses against OpenAPI specification and generates deterministic tests.

Community
Advanced