chore: add skills library

claude-skills/api-design-principles.md

@@ -0,0 +1,83 @@
+---
+name: api-design-principles
+description: Apply REST API design best practices when designing, reviewing, or building HTTP APIs. Covers naming, versioning, error handling, pagination, auth, and documentation.
+---
+
+# API Design Principles Skill
+
+Use when: designing a new API, reviewing an existing one, or writing API documentation.
+
+## URL & Resource Naming
+- Resources are **nouns**, never verbs: `/users` not `/getUsers`
+- Plural for collections: `/orders`, `/products`
+- Nested for ownership: `/users/{id}/orders`
+- Max 2 levels of nesting before using query params
+- kebab-case for multi-word: `/user-profiles`
+
+## HTTP Methods
+| Method | Use | Idempotent |
+|--------|-----|-----------|
+| GET | Read | Yes |
+| POST | Create | No |
+| PUT | Replace (full) | Yes |
+| PATCH | Update (partial) | No |
+| DELETE | Delete | Yes |
+
+## Status Codes
+- 200 OK — success with body
+- 201 Created — POST that made something (include Location header)
+- 204 No Content — success, no body (DELETE)
+- 400 Bad Request — client error, invalid input
+- 401 Unauthorized — not authenticated
+- 403 Forbidden — authenticated but not allowed
+- 404 Not Found — resource doesn't exist
+- 409 Conflict — state conflict (duplicate, version mismatch)
+- 422 Unprocessable — valid JSON but fails validation
+- 429 Too Many Requests — rate limited
+- 500 Internal Server Error — server fault
+
+## Error Response Format
+```json
+{
+  "error": {
+    "code": "VALIDATION_FAILED",
+    "message": "Human-readable explanation",
+    "details": [
+      { "field": "email", "message": "Must be a valid email" }
+    ]
+  }
+}
+```
+
+## Pagination
+Use cursor-based for large datasets, offset for small:
+```json
+{
+  "data": [...],
+  "pagination": {
+    "cursor": "abc123",
+    "hasMore": true,
+    "total": 1042
+  }
+}
+```
+
+## Versioning
+- URL path versioning: `/v1/users` (most visible, easiest to test)
+- Header versioning for internal APIs: `API-Version: 2024-01-01`
+- Never break v1 — deprecate with sunset dates
+
+## Auth
+- Use Bearer tokens: `Authorization: Bearer <token>`
+- API keys for server-to-server
+- OAuth 2.1 + PKCE for user-facing
+- Always HTTPS — no exceptions
+
+## Design Checklist
+- [ ] Resources are nouns, actions are HTTP methods
+- [ ] Consistent naming throughout (pick one style, stick to it)
+- [ ] All errors have machine-readable codes
+- [ ] Breaking changes increment version
+- [ ] Endpoints are documented (OpenAPI/Swagger preferred)
+- [ ] Rate limits documented and returning 429 with Retry-After header
+- [ ] Idempotency keys on POST for critical operations