api-design-framework

API Design Framework

Overview

This skill provides comprehensive guidance for designing robust, scalable, and developer-friendly APIs. Whether building REST, GraphQL, or gRPC services, this framework ensures consistency, usability, and maintainability.

When to use this skill:

• Designing new API endpoints or services
• Establishing API conventions for a team or organization
• Reviewing API designs for consistency and best practices
• Migrating or versioning existing APIs
• Creating API documentation (OpenAPI, AsyncAPI)
• Choosing between REST, GraphQL, or gRPC

API Design Principles

1. Developer Experience First

APIs should be intuitive and self-documenting:

• Clear, consistent naming conventions
• Predictable behavior and responses
• Comprehensive documentation
• Helpful error messages

2. Consistency Over Cleverness

Follow established patterns rather than inventing new ones:

• Standard HTTP methods and status codes (REST)
• Conventional query structures (GraphQL)
• Idiomatic proto definitions (gRPC)

3. Evolution Without Breaking Changes

Design for change from day one:

• API versioning strategy
• Backward compatibility considerations
• Deprecation policies
• Migration paths

4. Performance by Design

Consider performance implications:

• Pagination for large datasets
• Filtering and partial responses
• Caching strategies
• Rate limiting

---

REST API Design

Resource Naming Conventions

Use plural nouns for resources:

✅ GET /users
✅ GET /users/123
✅ GET /users/123/orders

❌ GET /user
❌ GET /getUser
❌ GET /user/123

Use hierarchical relationships:

✅ GET /users/123/orders          # Orders for specific user
✅ GET /teams/5/members           # Members of specific team
✅ POST /projects/10/tasks        # Create task in project 10

❌ GET /userOrders/123            # Flat structure
❌ GET /orders?userId=123         # Query param for relationship

Use kebab-case for multi-word resources:

✅ /shopping-carts
✅ /order-items
✅ /user-preferences

❌ /shoppingCarts    (camelCase)
❌ /shopping_carts   (snake_case)
❌ /ShoppingCarts    (PascalCase)