Api Design Principles

API Design Principles Skill

Master REST and GraphQL API design patterns for building intuitive, scalable, and maintainable APIs.

Overview

This skill provides comprehensive guidance on designing APIs that delight developers. It covers RESTful design principles, GraphQL schema design, versioning strategies, error handling, pagination, and best practices.

When to Use

• Designing new REST or GraphQL APIs
• Refactoring existing APIs for better usability
• Establishing API design standards for your team
• Reviewing API specifications before implementation
• Migrating between API paradigms
• Creating developer-friendly API documentation
• Optimizing APIs for specific use cases

Core Topics

REST APIs

• Resource-oriented architecture
• HTTP methods semantics (GET, POST, PUT, PATCH, DELETE)
• Pagination and filtering patterns
• Error handling and status codes
• HATEOAS (Hypermedia as the Engine of Application State)
• API versioning strategies

GraphQL APIs

• Schema-first development
• Type definitions and queries
• Mutations and subscriptions
• DataLoader for N+1 prevention
• Cursor-based pagination (Relay spec)

Auto-Trigger Keywords

• REST API design
• GraphQL schema
• API versioning
• HTTP methods
• pagination patterns
• error handling
• API documentation
• OpenAPI Swagger
• resource endpoints
• developer experience

Source

Adapted from wshobson/agents