api-design-principles

Design REST and GraphQL APIs with resource modeling, versioning, error handling, and pagination standards.

Updated Aug 23, 2026

Search Tags:#scalability #GraphQL #backend #REST #maintainability #developer experience #API design

One-click install

npx skills add https://github.com/Theopsguide/claude-agents --skill api-design-principles-theopsguide

Or copy as Structured Prompt for Agent▼

Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/Theopsguide/claude-agents/tree/main/plugins/backend-development/skills/api-design-principles
Command: npx skills add https://github.com/Theopsguide/claude-agents --skill api-design-principles-theopsguide

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes assets (resource) and references (resource) components.

What problem does it solve?

This Skill helps developers design robust, scalable, and maintainable APIs (REST & GraphQL) that are easy to use and evolve. It prevents common pitfalls like inconsistent design, poor error handling, and lack of versioning, ensuring your APIs delight developers and stand the test of time.

Core Features & Use Cases

RESTful & GraphQL Principles: Learn best practices for resource modeling, HTTP methods, schema design, and query optimization.
API Versioning: Implement strategies for evolving your API without breaking existing clients.
Error Handling & Pagination: Standardize error responses and efficiently manage large data sets.
Use Case: Design a new e-commerce API, ensuring it's intuitive for frontend developers, scalable for future growth, and maintainable for your team.

Quick Start

Example: RESTful Resource Collection Design

Good: Resource-oriented endpoints

GET /api/users # List users (with pagination) POST /api/users # Create user GET /api/users/{id} # Get specific user PUT /api/users/{id} # Replace user PATCH /api/users/{id} # Update user fields DELETE /api/users/{id} # Delete user