role-backend:api-implementation

API Implementation

When to use

• Building new API endpoints in any language or framework
• Adding or reordering middleware (auth, CORS, rate limiting, logging)
• Implementing error handling with RFC 7807 Problem Details
• Setting up tRPC, GraphQL, or OpenAPI spec generation
• Choosing a framework for a new backend service
• Implementing streaming responses (SSE, chunked JSON)
• Versioning an existing API

Core principles

1. Validate at the boundary — reject invalid input at the handler before any business logic runs
2. Middleware order is contract — request ID → CORS → rate limit → auth → validation → handler
3. RFC 7807 everywhere — all errors return Problem Details with type, title, status, correlationId
4. Never expose internals — no stack traces, no DB errors, no internal paths in responses
5. Schema-first serialization — use TypeBox/​Zod/​Pydantic for both validation and faster serialization

Reference Files

• references/​framework-selection.md — comparison tables for all frameworks across Node.js, Go, Rust, JVM, Python, .NET, Ruby, Elixir, PHP; pick the right tool before writing any code
• references/​framework-patterns.md — production-ready code examples for Hono, ElysiaJS, Fastify, Gin, Chi, Axum, Spring Boot 3, ASP.NET Core 8, and Phoenix; copy and adapt for the target stack
• references/​middleware-error-handling.md — middleware pipeline order, RFC 7807 error format, request validation rules, rate limiting config, CORS best practices
• references/​openapi-trpc-graphql.md — OpenAPI 3.1 codegen tools per framework, orval/​hey-api client generation, tRPC router setup, and GraphQL server implementations in Node.js, Python, Rust, and Go
• references/​versioning-streaming.md — API versioning strategy (URL path, content negotiation, deprecation headers), SSE streaming patterns, chunked JSON/​NDJSON for AI completions and bulk exports