ai-devx 1.0.0 → 1.0.2

package/templates/.agent/skills/api-patterns/SKILL.md

@@ -1,236 +1,81 @@
 ---
 name: api-patterns
-description: REST API design patterns, authentication, and best practices
-version: "1.0.0"
-requires: []
-related:
-  - backend-specialist
-  - security-best-practices
+description: API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.
+allowed-tools: Read, Write, Edit, Glob, Grep
 ---
 
-# API Patterns Skill
-
-## REST API Design
-
-### Resource Naming
-- Use nouns, not verbs
-- Use plural forms
-- Use kebab-case for multi-word resources
-
-```
-✅ GET    /users
-✅ GET    /users/:id
-✅ POST   /users
-✅ PUT    /users/:id
-✅ DELETE /users/:id
-✅ GET    /user-profiles
-
-❌ GET    /getUsers
-❌ GET    /getUserById
-❌ POST   /createUser
-```
-
-### HTTP Methods
-| Method | Action | Idempotent |
-|--------|--------|------------|
-| GET | Read | Yes |
-| POST | Create | No |
-| PUT | Update (full) | Yes |
-| PATCH | Update (partial) | No |
-| DELETE | Remove | Yes |
-
-### Status Codes
-- **200** - OK (GET, PUT, PATCH, DELETE)
-- **201** - Created (POST)
-- **204** - No Content (DELETE)
-- **400** - Bad Request
-- **401** - Unauthorized
-- **403** - Forbidden
-- **404** - Not Found
-- **409** - Conflict
-- **422** - Unprocessable Entity
-- **500** - Internal Server Error
-
-### Response Format
-```json
-{
-  "success": true,
-  "data": {
-    "id": "123",
-    "name": "John Doe"
-  },
-  "meta": {
-    "page": 1,
-    "limit": 10,
-    "total": 100
-  }
-}
-```
-
-### Error Response
-```json
-{
-  "success": false,
-  "error": {
-    "code": "VALIDATION_ERROR",
-    "message": "Invalid input data",
-    "details": [
-      {
-        "field": "email",
-        "message": "Invalid email format"
-      }
-    ]
-  }
-}
-```
-
-## Authentication Patterns
-
-### JWT Authentication
-```typescript
-// Login endpoint
-POST /auth/login
-{
-  "email": "user@example.com",
-  "password": "password123"
-}
-
-// Response
-{
-  "success": true,
-  "data": {
-    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
-    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
-    "expiresIn": 3600
-  }
-}
-
-// Protected endpoint
-GET /users
-Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
-```
-
-### API Key Authentication
-```
-GET /api/resources
-X-API-Key: your-api-key-here
-```
-
-## Pagination Patterns
-
-### Offset Pagination
-```
-GET /users?page=1&limit=20
-
-Response:
-{
-  "data": [...],
-  "meta": {
-    "page": 1,
-    "limit": 20,
-    "total": 100,
-    "totalPages": 5
-  }
-}
-```
-
-### Cursor Pagination
-```
-GET /users?cursor=xyz&limit=20
-
-Response:
-{
-  "data": [...],
-  "meta": {
-    "nextCursor": "abc",
-    "hasMore": true
-  }
-}
-```
-
-## Filtering & Sorting
-
-```
-GET /users?role=admin&status=active&sort=-created_at,name
-
-// Multiple filters (OR)
-GET /users?role=admin,moderator
-
-// Range filters
-GET /orders?created_at[gte]=2024-01-01&created_at[lte]=2024-12-31
-
-// Full-text search
-GET /products?q=laptop&category=electronics
-```
-
-## Validation Patterns
-
-### Input Validation
-```typescript
-// Using Zod
-const createUserSchema = z.object({
-  email: z.string().email(),
-  password: z.string().min(8),
-  name: z.string().min(1).max(100),
-  age: z.number().int().min(0).optional()
-});
-
-// Middleware
-app.post('/users', validate(createUserSchema), createUserHandler);
-```
-
-## Rate Limiting
-```
-Headers:
-X-RateLimit-Limit: 100
-X-RateLimit-Remaining: 95
-X-RateLimit-Reset: 1640995200
-```
-
-## API Versioning
-
-### URL Versioning
-```
-/api/v1/users
-/api/v2/users
-```
-
-### Header Versioning
-```
-Accept: application/vnd.api+json;version=1
-```
-
-## Best Practices
-
-### 1. Idempotency
-```
-Idempotency-Key: unique-key-for-request
-```
-
-### 2. Caching Headers
-```
-Cache-Control: max-age=3600
-ETag: "abc123"
-Last-Modified: Wed, 21 Oct 2024 07:28:00 GMT
-```
-
-### 3. Request IDs
-```
-X-Request-ID: uuid-for-tracing
-```
-
-### 4. Documentation
-- Use OpenAPI/Swagger
-- Include examples
-- Document error cases
-
-## Security Checklist
-- [ ] HTTPS only
-- [ ] Input validation
-- [ ] Authentication on protected routes
-- [ ] Authorization checks
-- [ ] Rate limiting
-- [ ] CORS configuration
-- [ ] Security headers
-- [ ] SQL injection prevention
-- [ ] XSS protection
+# API Patterns
+
+> API design principles and decision-making for 2025.
+> **Learn to THINK, not copy fixed patterns.**
+
+## 🎯 Selective Reading Rule
+
+**Read ONLY files relevant to the request!** Check the content map, find what you need.
+
+---
+
+## 📑 Content Map
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| `api-style.md` | REST vs GraphQL vs tRPC decision tree | Choosing API type |
+| `rest.md` | Resource naming, HTTP methods, status codes | Designing REST API |
+| `response.md` | Envelope pattern, error format, pagination | Response structure |
+| `graphql.md` | Schema design, when to use, security | Considering GraphQL |
+| `trpc.md` | TypeScript monorepo, type safety | TS fullstack projects |
+| `versioning.md` | URI/Header/Query versioning | API evolution planning |
+| `auth.md` | JWT, OAuth, Passkey, API Keys | Auth pattern selection |
+| `rate-limiting.md` | Token bucket, sliding window | API protection |
+| `documentation.md` | OpenAPI/Swagger best practices | Documentation |
+| `security-testing.md` | OWASP API Top 10, auth/authz testing | Security audits |
+
+---
+
+## 🔗 Related Skills
+
+| Need | Skill |
+|------|-------|
+| API implementation | `@[skills/backend-development]` |
+| Data structure | `@[skills/database-design]` |
+| Security details | `@[skills/security-hardening]` |
+
+---
+
+## ✅ Decision Checklist
+
+Before designing an API:
+
+- [ ] **Asked user about API consumers?**
+- [ ] **Chosen API style for THIS context?** (REST/GraphQL/tRPC)
+- [ ] **Defined consistent response format?**
+- [ ] **Planned versioning strategy?**
+- [ ] **Considered authentication needs?**
+- [ ] **Planned rate limiting?**
+- [ ] **Documentation approach defined?**
+
+---
+
+## ❌ Anti-Patterns
+
+**DON'T:**
+- Default to REST for everything
+- Use verbs in REST endpoints (/getUsers)
+- Return inconsistent response formats
+- Expose internal errors to clients
+- Skip rate limiting
+
+**DO:**
+- Choose API style based on context
+- Ask about client requirements
+- Document thoroughly
+- Use appropriate status codes
+
+---
+
+## Script
+
+| Script | Purpose | Command |
+|--------|---------|---------|
+| `scripts/api_validator.py` | API endpoint validation | `python scripts/api_validator.py <project_path>` |
+

package/templates/.agent/skills/api-patterns/api-style.md

@@ -0,0 +1,42 @@
+# API Style Selection (2025)
+
+> REST vs GraphQL vs tRPC - Hangi durumda hangisi?
+
+## Decision Tree
+
+```
+Who are the API consumers?
+│
+├── Public API / Multiple platforms
+│   └── REST + OpenAPI (widest compatibility)
+│
+├── Complex data needs / Multiple frontends
+│   └── GraphQL (flexible queries)
+│
+├── TypeScript frontend + backend (monorepo)
+│   └── tRPC (end-to-end type safety)
+│
+├── Real-time / Event-driven
+│   └── WebSocket + AsyncAPI
+│
+└── Internal microservices
+    └── gRPC (performance) or REST (simplicity)
+```
+
+## Comparison
+
+| Factor | REST | GraphQL | tRPC |
+|--------|------|---------|------|
+| **Best for** | Public APIs | Complex apps | TS monorepos |
+| **Learning curve** | Low | Medium | Low (if TS) |
+| **Over/under fetching** | Common | Solved | Solved |
+| **Type safety** | Manual (OpenAPI) | Schema-based | Automatic |
+| **Caching** | HTTP native | Complex | Client-based |
+
+## Selection Questions
+
+1. Who are the API consumers?
+2. Is the frontend TypeScript?
+3. How complex are the data relationships?
+4. Is caching critical?
+5. Public or internal API?

package/templates/.agent/skills/api-patterns/auth.md

@@ -0,0 +1,24 @@
+# Authentication Patterns
+
+> Choose auth pattern based on use case.
+
+## Selection Guide
+
+| Pattern | Best For |
+|---------|----------|
+| **JWT** | Stateless, microservices |
+| **Session** | Traditional web, simple |
+| **OAuth 2.0** | Third-party integration |
+| **API Keys** | Server-to-server, public APIs |
+| **Passkey** | Modern passwordless (2025+) |
+
+## JWT Principles
+
+```
+Important:
+├── Always verify signature
+├── Check expiration
+├── Include minimal claims
+├── Use short expiry + refresh tokens
+└── Never store sensitive data in JWT
+```

package/templates/.agent/skills/api-patterns/documentation.md

@@ -0,0 +1,26 @@
+# API Documentation Principles
+
+> Good docs = happy developers = API adoption.
+
+## OpenAPI/Swagger Essentials
+
+```
+Include:
+├── All endpoints with examples
+├── Request/response schemas
+├── Authentication requirements
+├── Error response formats
+└── Rate limiting info
+```
+
+## Good Documentation Has
+
+```
+Essentials:
+├── Quick start / Getting started
+├── Authentication guide
+├── Complete API reference
+├── Error handling guide
+├── Code examples (multiple languages)
+└── Changelog
+```

package/templates/.agent/skills/api-patterns/graphql.md

@@ -0,0 +1,41 @@
+# GraphQL Principles
+
+> Flexible queries for complex, interconnected data.
+
+## When to Use
+
+```
+✅ Good fit:
+├── Complex, interconnected data
+├── Multiple frontend platforms
+├── Clients need flexible queries
+├── Evolving data requirements
+└── Reducing over-fetching matters
+
+❌ Poor fit:
+├── Simple CRUD operations
+├── File upload heavy
+├── HTTP caching important
+└── Team unfamiliar with GraphQL
+```
+
+## Schema Design Principles
+
+```
+Principles:
+├── Think in graphs, not endpoints
+├── Design for evolvability (no versions)
+├── Use connections for pagination
+├── Be specific with types (not generic "data")
+└── Handle nullability thoughtfully
+```
+
+## Security Considerations
+
+```
+Protect against:
+├── Query depth attacks → Set max depth
+├── Query complexity → Calculate cost
+├── Batching abuse → Limit batch size
+├── Introspection → Disable in production
+```

package/templates/.agent/skills/api-patterns/rate-limiting.md

@@ -0,0 +1,31 @@
+# Rate Limiting Principles
+
+> Protect your API from abuse and overload.
+
+## Why Rate Limit
+
+```
+Protect against:
+├── Brute force attacks
+├── Resource exhaustion
+├── Cost overruns (if pay-per-use)
+└── Unfair usage
+```
+
+## Strategy Selection
+
+| Type | How | When |
+|------|-----|------|
+| **Token bucket** | Burst allowed, refills over time | Most APIs |
+| **Sliding window** | Smooth distribution | Strict limits |
+| **Fixed window** | Simple counters per window | Basic needs |
+
+## Response Headers
+
+```
+Include in headers:
+├── X-RateLimit-Limit (max requests)
+├── X-RateLimit-Remaining (requests left)
+├── X-RateLimit-Reset (when limit resets)
+└── Return 429 when exceeded
+```

package/templates/.agent/skills/api-patterns/response.md

@@ -0,0 +1,37 @@
+# Response Format Principles
+
+> Consistency is key - choose a format and stick to it.
+
+## Common Patterns
+
+```
+Choose one:
+├── Envelope pattern ({ success, data, error })
+├── Direct data (just return the resource)
+└── HAL/JSON:API (hypermedia)
+```
+
+## Error Response
+
+```
+Include:
+├── Error code (for programmatic handling)
+├── User message (for display)
+├── Details (for debugging, field-level errors)
+├── Request ID (for support)
+└── NOT internal details (security!)
+```
+
+## Pagination Types
+
+| Type | Best For | Trade-offs |
+|------|----------|------------|
+| **Offset** | Simple, jumpable | Performance on large datasets |
+| **Cursor** | Large datasets | Can't jump to page |
+| **Keyset** | Performance critical | Requires sortable key |
+
+### Selection Questions
+
+1. How large is the dataset?
+2. Do users need to jump to specific pages?
+3. Is data frequently changing?

package/templates/.agent/skills/api-patterns/rest.md

@@ -0,0 +1,40 @@
+# REST Principles
+
+> Resource-based API design - nouns not verbs.
+
+## Resource Naming Rules
+
+```
+Principles:
+├── Use NOUNS, not verbs (resources, not actions)
+├── Use PLURAL forms (/users not /user)
+├── Use lowercase with hyphens (/user-profiles)
+├── Nest for relationships (/users/123/posts)
+└── Keep shallow (max 3 levels deep)
+```
+
+## HTTP Method Selection
+
+| Method | Purpose | Idempotent? | Body? |
+|--------|---------|-------------|-------|
+| **GET** | Read resource(s) | Yes | No |
+| **POST** | Create new resource | No | Yes |
+| **PUT** | Replace entire resource | Yes | Yes |
+| **PATCH** | Partial update | No | Yes |
+| **DELETE** | Remove resource | Yes | No |
+
+## Status Code Selection
+
+| Situation | Code | Why |
+|-----------|------|-----|
+| Success (read) | 200 | Standard success |
+| Created | 201 | New resource created |
+| No content | 204 | Success, nothing to return |
+| Bad request | 400 | Malformed request |
+| Unauthorized | 401 | Missing/invalid auth |
+| Forbidden | 403 | Valid auth, no permission |
+| Not found | 404 | Resource doesn't exist |
+| Conflict | 409 | State conflict (duplicate) |
+| Validation error | 422 | Valid syntax, invalid data |
+| Rate limited | 429 | Too many requests |
+| Server error | 500 | Our fault |