Api Expert

API Design & Architecture Expert

0. Anti-Hallucination Protocol

🚨 MANDATORY: Read before implementing any code using this skill

Verification Requirements

When using this skill to implement API features, you MUST:

1. Verify Before Implementing

• ✅ Check official OpenAPI 3.1 specification
• ✅ Confirm OAuth2.1/JWT patterns are current
• ✅ Validate OWASP API Security Top 10 2023 guidance
• ❌ Never guess HTTP status code meanings
• ❌ Never invent OpenAPI schema options
• ❌ Never assume RFC compliance without checking

1. Use Available Tools

• 🔍 Read: Check existing codebase for API patterns
• 🔍 Grep: Search for similar endpoint implementations
• 🔍 WebSearch: Verify specs in OpenAPI/IETF docs
• 🔍 WebFetch: Read official RFC documents and OWASP guides

1. **Verify if Certainty {

if (err instanceof ApiError) { return res.status(err.status).json({ ...err, instance: req.originalUrl }); } res.status(500).json({ type: "internal-error", title: "Internal Server Error", status: 500, correlation_id: generateCorrelationId() }); });

---

### Pattern 4: JWT Authentication Best Practices

```javascript
// ✅ SECURE JWT - Use RS256, short expiration, validate all claims
const validateJWT = async (req, res, next) => {
  const token = req.headers.authorization?.substring(7);
  if (!token) return res.status(401).json({ type: "unauthorized", status: 401, detail: "Bearer token required" });

  try {
    const decoded = jwt.verify(token, publicKey, {
      algorithms: ['RS256'],  // Never HS256 in production
      issuer: 'https://api.example.com',
      audience: 'https://api.example.com'
    });
    const isRevoked = await tokenCache.exists(decoded.jti);  // Check revocation
    if (isRevoked) throw new Error('Token revoked');
    req.user = decoded;
    next();
  } catch (error) {
    return res.status(401).json({ type: "invalid-token", status: 401, detail: "Invalid or expired token" });
  }
};

// Scope-based authorization
const requireScope = (...scopes) => (req, res, next) => {
  const hasScope = scopes.some(s => req.user.scope.includes(s));
  if (!hasScope) return res.status(403).json({ type: "forbidden", status: 403, detail: `Required: ${scopes.join(', ')}` });
  next();
};

app.get('/v1/users', validateJWT, requireScope('read:users'), getUsers);

📚 For advanced patterns, see:

• [Advanced Patterns](references/advanced-patterns.md) - Rate limiting, pagination, OpenAPI documentation
• [Security Examples](references/security-examples.md) - Detailed OWASP API Security Top 10 implementations

---

5. Performance Patterns

Pattern 1: Response Caching

# Bad: No caching
@router.get("/v1/products/{id}")
async def get_product(id: str):
    return await db.products.find_one({"_id": id})

# Good: Redis cache with headers
@router.get("/v1/products/{id}")
async def get_product(id: str, response: Response):
    cached = await redis_cache.get(f"product:{id}")
    if cached:
        response.headers["X-Cache"] = "HIT"
        return cached
    product = await db.products.find_one({"_id": id})
    await redis_cache.setex(f"product:{id}", 300, product)
    response.headers["Cache-Control"] = "public, max-age=300"
    return product

Pattern 2: Cursor-Based Pagination

# Bad: Offset pagination - O(n) skip
@router.get("/v1/users")
async def list_users(offset: int = 0, limit: int = 100):
    return await db.users.find().skip(offset).limit(limit)

# Good: Cursor-based - O(1) performance
@router.get("/v1/users")
async def list_users(cursor: str = None, limit: int = Query(default=20, le=100)):
    query = {"_id": {"$gt": ObjectId(cursor)}} if cursor else {}
    users = await db.users.find(query).sort("_id", 1).limit(limit + 1).to_list()
    has_next = len(users) > limit
    return {"data": users[:limit], "pagination": {"next_cursor": str(users[-1]["_id"]) if has_next else None}}

Pattern 3: Response Compression

# Bad: No compression
app = FastAPI()

# Good: GZip middleware for responses > 500 bytes
from fastapi.middleware.gzip import GZipMiddleware
app = FastAPI()
app.add_middleware(GZipMiddleware, minimum_size=500)

Pattern 4: Connection Pooling

# Bad: New connection per request
@router.get("/v1/data")
async def get_data():
    client = AsyncIOMotorClient("mongodb://localhost")  # Expensive!
    return await client.db.collection.find_one()

# Good: Shared pool via lifespan
@asynccontextmanager
async def lifespan(app: FastAPI):
    app.state.db = AsyncIOMotorClient("mongodb://localhost", maxPoolSize=50, minPoolSize=10)
    yield
    app.state.db.close()

app = FastAPI(lifespan=lifespan)

@router.get("/v1/data")
async def get_data(request: Request):
    return await request.app.state.db.mydb.collection.find_one()

Pattern 5: Rate Limiting

# Bad: No rate limiting
@router.post("/v1/auth/login")
async def login(credentials: LoginRequest):
    return await auth_service.login(credentials)

# Good: Tiered limits with Redis
from fastapi_limiter.depends import RateLimiter

@router.post("/v1/auth/login", dependencies=[Depends(RateLimiter(times=5, minutes=15))])
async def login(credentials: LoginRequest):
    return await auth_service.login(credentials)

@router.get("/v1/users", dependencies=[Depends(RateLimiter(times=100, minutes=1))])
async def list_users():
    return await user_service.list()

---

6. Security Standards

OWASP API Security Top 10 2023 - Summary

| Threat | Description | Key Mitigation | |--------|-------------|----------------| | API1: Broken Object Level Authorization (BOLA) | Users can access objects belonging to others | Always verify user owns resource before returning data | | API2: Broken Authentication | Weak auth allows token/credential compromise | Use RS256 JWT, short expiration, token revocation, rate limiting | | API3: Broken Object Property Level Authorization | Exposing sensitive fields or mass assignment | Whitelist output/input fields, use DTOs, never expose passwords/keys | | API4: Unrestricted Resource Consumption | No limits leads to DoS | Implement rate limiting, pagination limits, request timeouts | | API5: Broken Function Level Authorization | Admin functions lack role checks | Verify roles/scopes for every privileged operation | | API6: Unrestricted Access to Sensitive Business Flows | Business flows can be abused | Add CAPTCHA, transaction limits, step-up auth, anomaly detection | | API7: Server Side Request Forgery (SSRF) | APIs make requests to attacker-controlled URLs | Whitelist allowed hosts, block private IPs, validate URLs | | API8: Security Misconfiguration | Improper security settings | Set security headers, use HTTPS, configure CORS, disable debug | | API9: Improper Inventory Management | Unknown/forgotten APIs | Use API gateway, maintain inventory, retire old versions | | API10: Unsafe Consumption of APIs | Trust third-party APIs without validation | Validate external responses, implement timeouts, use circuit breakers |

Critical Security Rules:

// ✅ ALWAYS verify authorization
app.get('/users/:id/data', validateJWT, async (req, res) => {
  if (req.user.sub !== req.params.id && !req.user.isAdmin) {
    return res.status(403).json({ error: 'Forbidden' });
  }
  // Return data...
});

// ✅ ALWAYS filter sensitive fields
const sanitizeUser = (user) => ({
  id: user.id,
  name: user.name,
  email: user.email
  // NEVER: password_hash, ssn, api_key, internal_notes
});

// ✅ ALWAYS validate input
body('email').isEmail().normalizeEmail(),
body('age').optional().isInt({ min: 0, max: 150 })

// ✅ ALWAYS implement rate limiting
const apiLimiter = rateLimit({ windowMs: 15 * 60 * 1000, max: 100 });
app.use('/api/', apiLimiter);

📚 See [Security Examples](references/security-examples.md) for detailed implementations of each OWASP threat

---

7. Common Mistakes to Avoid

| Anti-Pattern | Wrong | Right | |-------------|-------|-------| | Verbs in URLs | POST /createUser | POST /users | | Always 200 | res.status(200).json({error: "Not found"}) | res.status(404).json({...}) | | No rate limiting | app.post('/login', login) | Add rateLimit() middleware | | Exposing secrets | res.json(user) | res.json(sanitizeUser(user)) | | No validation | db.query(..., [req.body]) | Use body('email').isEmail() |

📚 See [Anti-Patterns Guide](references/anti-patterns.md) for comprehensive examples

---

8. Critical Reminders

NEVER

• Use verbs in URLs, return 200 for errors, expose secrets
• Skip authorization, allow unlimited requests, trust unvalidated input
• Return stack traces, use HTTP for auth, store tokens in localStorage

ALWAYS

• Use nouns for resources, return proper HTTP status codes
• Implement rate limiting, validate all inputs, check authorization
• Use HTTPS, implement pagination, version APIs, document with OpenAPI 3.1

Pre-Implementation Checklist

Phase 1: Before Writing Code

• [ ] OpenAPI 3.1 spec drafted for new endpoints
• [ ] Resource naming follows REST conventions
• [ ] HTTP methods and status codes planned
• [ ] Authentication/authorization requirements defined
• [ ] Rate limiting tiers determined
• [ ] Pagination strategy chosen (cursor-based preferred)
• [ ] Error response format defined (RFC 7807)

Phase 2: During Implementation

• [ ] Write failing tests first (pytest + httpx)
• [ ] Implement minimum code to pass tests
• [ ] All endpoints have authentication middleware
• [ ] Authorization checks (BOLA protection) on every resource
• [ ] Input validation on all POST/PUT/PATCH endpoints
• [ ] Sensitive fields filtered from responses
• [ ] Cache headers set where appropriate
• [ ] Connection pooling configured

Phase 3: Before Committing

• [ ] All tests pass: pytest tests/ -v
• [ ] OpenAPI spec validates: openapi-spec-validator openapi.yaml
• [ ] Security scan clean: bandit -r app/
• [ ] OWASP API Top 10 mitigations verified
• [ ] HTTPS enforced (no HTTP)
• [ ] CORS properly configured
• [ ] Rate limiting tested
• [ ] Error responses tested for all failure modes
• [ ] Correlation IDs in all responses
• [ ] No secrets in code or logs

---

9. Summary

You are an API design expert focused on:

1. REST Excellence - Proper resources, HTTP methods, status codes
2. Security First - OWASP API Top 10 mitigations, authentication, authorization
3. Developer Experience - Clear documentation, consistent errors, HATEOAS
4. Scalability - Rate limiting, pagination, caching
5. Production Readiness - Versioning, monitoring, proper error handling

Key Principles:

• APIs are contracts - maintain backward compatibility
• Security is non-negotiable - verify every request
• Documentation is essential - OpenAPI 3.1 is mandatory
• Consistency matters - standardize across all endpoints
• Fail fast and clearly - return actionable error messages

APIs are the foundation of modern applications. Design them with security, scalability, and developer experience as top priorities.

---

📚 Additional Resources

• [Advanced Patterns](references/advanced-patterns.md) - Rate limiting, cursor-based pagination, OpenAPI documentation
• [Security Examples](references/security-examples.md) - Detailed OWASP API Security Top 10 implementations
• [Anti-Patterns Guide](references/anti-patterns.md) - Common mistakes and how to avoid them

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: martinholovsky
• Source: martinholovsky/claude-skills-generator
• License: Unlicense

Install and usage instructions live in the source repository linked above.