api-design-principles

1# API Design Principles
2 
3Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.
4 
5## When to Use This Skill
6 
7- Designing new REST or GraphQL APIs
8- Refactoring existing APIs for better usability
9- Establishing API design standards for your team
10- Reviewing API specifications before implementation
11- Migrating between API paradigms (REST to GraphQL, etc.)
12- Creating developer-friendly API documentation
13- Optimizing APIs for specific use cases (mobile, third-party integrations)
14 
15## Core Concepts
16 
17### 1. RESTful Design Principles
18 
19**Resource-Oriented Architecture**
20 
21- Resources are nouns (users, orders, products), not verbs
22- Use HTTP methods for actions (GET, POST, PUT, PATCH, DELETE)
23- URLs represent resource hierarchies
24- Consistent naming conventions
25 
26**HTTP Methods Semantics:**
27 
28- `GET`: Retrieve resources (idempotent, safe)
29- `POST`: Create new resources
30- `PUT`: Replace entire resource (idempotent)
31- `PATCH`: Partial resource updates
32- `DELETE`: Remove resources (idempotent)
33 
34### 2. GraphQL Design Principles
35 
36**Schema-First Development**
37 
38- Types define your domain model
39- Queries for reading data
40- Mutations for modifying data
41- Subscriptions for real-time updates
42 
43**Query Structure:**
44 
45- Clients request exactly what they need
46- Single endpoint, multiple operations
47- Strongly typed schema
48- Introspection built-in
49 
50### 3. API Versioning Strategies
51 
52**URL Versioning:**
53 
54```
55…