---

name: innozverse-api-style description: Follow API development conventions including RESTful design, Fastify patterns, Zod validation, error handling, and versioning. Use when building API endpoints, adding routes, or working with API code.

innozverse API Development Style

When developing API endpoints for innozverse, follow these patterns and conventions.

Fastify Basics

Route Registration

Copy// apps/api/src/routes/v1/users.ts
import { FastifyInstance } from 'fastify';

export async function usersRoutes(fastify: FastifyInstance) {
  fastify.get('/users', async (request, reply) => {
    return { users: [] };
  });

  fastify.get('/users/:id', async (request, reply) => {
    const { id } = request.params as { id: string };
    return { user: { id } };
  });

  fastify.post('/users', async (request, reply) => {
    const body = request.body;
    return reply.code(201).send({ user: body });
  });
}

Register in Index

Copy// apps/api/src/index.ts
import { usersRoutes } from './routes/v1/users';

fastify.register(usersRoutes, { prefix: '/v1' });

Response Patterns

Success Response

Copyreturn reply.code(200).send({
  status: 'ok',
  data: { /* ... */ }
});

Created Response

Copyreturn reply.code(201).send({
  status: 'created',
  data: { id: newId }
});

Error Response

Copyreturn reply.code(400).send({
  error: 'ValidationError',
  message: 'Invalid input',
  statusCode: 400
});

Type Safety

Define Types in @innozverse/shared

Copy// packages/shared/src/types.ts
export interface User {
  id: string;
  name: string;
  email: string;
}

export interface UserResponse {
  status: 'ok';
  data: User;
}

Use in API

Copyimport { User, UserResponse } from '@innozverse/shared';

fastify.get<{ Reply: UserResponse }>('/users/:id', async (request, reply) => {
  const user: User = { /* ... */ };
  return reply.send({
    status: 'ok',
    data: user
  });
});

Validation with Zod

Define Schema in @innozverse/shared

Copy// packages/shared/src/schemas.ts
import { z } from 'zod';

export const userSchema = z.object({
  name: z.string().min(1),
  email: z.string().email()
});

Use in API

Copyimport { userSchema } from '@innozverse/shared';

fastify.post('/users', async (request, reply) => {
  try {
    const validated = userSchema.parse(request.body);
    // Use validated data
    return reply.code(201).send({ data: validated });
  } catch (error) {
    return reply.code(400).send({
      error: 'ValidationError',
      message: error.message
    });
  }
});

Error Handling

Global Error Handler

Copy// apps/api/src/index.ts
fastify.setErrorHandler((error, request, reply) => {
  fastify.log.error(error);

  reply.status(error.statusCode || 500).send({
    error: error.name || 'InternalServerError',
    message: error.message || 'Something went wrong',
    statusCode: error.statusCode || 500
  });
});

Throwing Errors

Copyfastify.get('/users/:id', async (request, reply) => {
  const user = await findUser(id);

  if (!user) {
    return reply.code(404).send({
      error: 'NotFound',
      message: 'User not found',
      statusCode: 404
    });
  }

  return { data: user };
});

Async/Await

Always use async/await, never callbacks:

Copy// ✅ Good
fastify.get('/users', async (request, reply) => {
  const users = await getUsers();
  return { users };
});

// ❌ Bad
fastify.get('/users', (request, reply) => {
  getUsers((err, users) => {
    reply.send({ users });
  });
});

RESTful Conventions

Resource Naming

• Plural nouns: /users, /posts
• Nested resources: /users/:userId/posts

HTTP Methods

• GET /resource - List all
• GET /resource/:id - Get one
• POST /resource - Create
• PUT /resource/:id - Replace
• PATCH /resource/:id - Update
• DELETE /resource/:id - Delete

Status Codes

• 200 - Success (GET, PUT, PATCH, DELETE)
• 201 - Created (POST)
• 204 - No Content (DELETE)
• 400 - Bad Request (validation error)
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
• 409 - Conflict (duplicate)
• 500 - Internal Server Error

Versioning

Always version API routes:

Copy// ✅ Good
fastify.register(v1Routes, { prefix: '/v1' });
fastify.register(v2Routes, { prefix: '/v2' });

// ❌ Bad
fastify.register(routes); // No version

CORS Configuration

Copyimport cors from '@fastify/cors';

await fastify.register(cors, {
  origin: process.env.CORS_ORIGIN || '*',
  credentials: true
});

Environment Variables

Copyconst PORT = parseInt(process.env.PORT || '8080', 10);
const NODE_ENV = process.env.NODE_ENV || 'development';

// Never hardcode secrets
const DB_URL = process.env.DATABASE_URL; // ✅
const API_KEY = process.env.API_KEY; // ✅

Logging

Copy// Use Fastify's built-in logger
fastify.log.info('Server starting');
fastify.log.error({ err: error }, 'Error occurred');
fastify.log.debug({ data }, 'Debug info');

Health Check

Always maintain a health check endpoint:

Copyfastify.get('/health', async () => ({
  status: 'ok',
  timestamp: new Date().toISOString(),
  version: process.env.API_VERSION || '1.0.0'
}));

Testing (Future)

Copy// apps/api/src/routes/__tests__/users.test.ts
import { buildServer } from '../../index';

describe('Users API', () => {
  let fastify;

  beforeAll(async () => {
    fastify = await buildServer();
  });

  afterAll(async () => {
    await fastify.close();
  });

  test('GET /v1/users returns users list', async () => {
    const response = await fastify.inject({
      method: 'GET',
      url: '/v1/users'
    });

    expect(response.statusCode).toBe(200);
    expect(response.json()).toHaveProperty('users');
  });
});

Database Patterns (Future)

When adding database:

Copy// Use a connection pool
import { Pool } from 'pg';

const pool = new Pool({
  connectionString: process.env.DATABASE_URL
});

// Close connections gracefully
fastify.addHook('onClose', async () => {
  await pool.end();
});

// Use in routes
fastify.get('/users/:id', async (request, reply) => {
  const { rows } = await pool.query(
    'SELECT * FROM users WHERE id = $1',
    [request.params.id]
  );

  if (rows.length === 0) {
    return reply.code(404).send({ error: 'Not found' });
  }

  return { data: rows[0] };
});

Best Practices

Single Responsibility

Each route file handles one resource:

Copyroutes/v1/
├── users.ts      # User management
├── posts.ts      # Post management
└── comments.ts   # Comment management

DRY Principles

Extract common logic:

Copy// utils/auth.ts
export async function requireAuth(request, reply) {
  const token = request.headers.authorization;
  if (!token) {
    return reply.code(401).send({ error: 'Unauthorized' });
  }
  // Verify token
}

// routes/v1/users.ts
fastify.get('/users/me', {
  preHandler: requireAuth
}, async (request, reply) => {
  return { user: request.user };
});

Graceful Shutdown

Copyprocess.on('SIGTERM', async () => {
  await fastify.close();
  process.exit(0);
});

Anti-Patterns to Avoid

❌ Don't use any types:

Copy// Bad
fastify.get('/users', async (request: any, reply: any) => {

❌ Don't block the event loop:

Copy// Bad
fastify.get('/heavy', async () => {
  let result = 0;
  for (let i = 0; i < 1000000000; i++) {
    result += i;
  }
  return { result };
});

❌ Don't ignore errors:

Copy// Bad
fastify.get('/users', async () => {
  const users = await getUsers().catch(() => []);
  return { users };
});

❌ Don't expose internal errors to clients:

Copy// Bad
return reply.code(500).send({ error: error.stack });

// Good
fastify.log.error(error);
return reply.code(500).send({ error: 'Internal Server Error' });

References

• Fastify Documentation
• Zod Documentation
• RESTful API Design