06-api-development

REST API

Routing & Handler Structure

• Define routes inline for simplicity
  Avoid traditional "controller" layers. Use route handlers directly with Hono for better type inference and simpler structure.

  app.get('/books/:id', (c) => {
    const id = c.req.param('id');
    return c.json({ id });
  });
  

• Modularize routes by feature
  Use app.route() to separate route logic into distinct modules.

  // routes/books.ts
  import { Hono } from 'hono';
  
  const books = new Hono();
  
  books.get('/', (c) => c.json(['book1', 'book2']));
  books.get('/:id', (c) => c.json({ id: c.req.param('id') }));
  
  export default books;
  
  // main.ts
  import books from './routes/books';
  const app = new Hono();
  app.route('/books', books);
  

Type Safety & Validation with Zod

• Use Zod for schema validation
  Combine zod and @hono/zod-validator for strict runtime and compile-time validation.

  import { z } from 'zod';
  import { zValidator } from '@hono/zod-validator';
  
  const userSchema = z.object({
    name: z.string(),
  });
  
  app.post('/users', zValidator('json', userSchema), (c) => {
    const data = c.req.valid('json');
    return c.json({ message: `Hello, ${data.name}` });
  });
  

• Always validate request bodies, query params, and route params to prevent runtime issues and improve DX.

Middleware Usage

• Built-in Middleware
  Use Hono's middleware for logging, CORS, etc.

  import { logger } from 'hono/logger';
  import { cors } from 'hono/cors';
  
  app.use('*', logger());
  app.use('*', cors());
  

• Custom Middleware for JWT and API key Auth (see auth.ts)

Authorization & Organization Scoping

• Authentication & Context Establishment:
  • Authentication is handled by custom middleware detailed in [auth.ts](mdc:apps/api/src/auth.ts).
  • This middleware supports both JWT (JSON Web Tokens) for user sessions and API Keys for programmatic access.
  • Upon successful authentication, the middleware establishes the organizationId in the request context (e.g., c.set("organizationId", ...)) based on the authenticated user or API key.