examples

Examples

This directory contains working examples demonstrating different features of @bitfocusas/api.

🚀 Quick Start

All examples can be run directly using tsx:

# Simple example - minimal setup
npm run example:simple

# Basic example - user CRUD with validation
npm run example:basic

# Custom auth example - JWT/token validation with typed context
npm run example:auth

# Custom Fastify example - use your own Fastify instance
npm run example:fastify

Or run them directly:

npx tsx examples/simple.ts
npx tsx examples/basic.ts
npx tsx examples/custom-auth.ts
npx tsx examples/custom-fastify.ts

📚 Available Examples

1. simple.ts - Hello World

The absolute minimum code to get started. Perfect for understanding the basics.

Features:

• Minimal configuration
• Simple GET endpoint
• Query parameter validation
• Auto-generated Swagger docs

Run: npm run example:simple

---

2. basic.ts - User Management API

A more complete example with CRUD operations and validation.

Features:

• POST and GET endpoints
• Request/response validation
• Custom validation errors
• In-memory data store
• Swagger documentation

Run: npm run example:basic

Try it:

# Create a user
curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{"name":"John Doe","email":"john@example.com","age":30}'

# Get all users
curl http://localhost:3000/users

---

3. custom-fastify.ts - Using Your Own Fastify Instance

Example showing how to attach the API server to your existing Fastify instance.

Features:

• Custom Fastify instance with your own configuration
• Register plugins before attaching API server
• Add custom routes alongside API endpoints
• Full control over Fastify lifecycle

Run: npm run example:fastify

Use cases:

• Integrating with existing Fastify applications
• Sharing a Fastify instance across modules
• Using custom Fastify plugins
• More control over server configuration

Try it:

# Health check (custom route)
curl http://localhost:3000/health

# List users (API endpoint)
curl http://localhost:3000/users?limit=2

# Create user (API endpoint)
curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{"name":"John Doe","email":"john@example.com"}'

---

4. custom-auth.ts - Authentication & Authorization

Advanced example showing custom token validation with typed context.

Features:

• Custom token validation function
• Typed authentication context
• Role-based access control (RBAC)
• Permission checking
• Public and protected endpoints

Run: npm run example:auth

Try it:

# Public endpoint (no auth)
curl http://localhost:3000/public

# Protected endpoint with user token
curl -H "Authorization: Bearer user-token-456" \
  http://localhost:3000/profile

# Admin-only endpoint
curl -X DELETE \
  -H "Authorization: Bearer admin-token-123" \
  http://localhost:3000/admin/users/123

Tokens in this example:

• admin-token-123 - Admin user with full permissions
• user-token-456 - Regular user with read-only access

---

💡 Tips

1. Visit Swagger UI: All examples include auto-generated docs at http://localhost:3000/docs

2. Enable Metrics: Check Prometheus metrics at http://localhost:3000/metrics

3. Debug Logging: Set environment variable for detailed logs:

   LOG_LEVEL=debug npx tsx examples/basic.ts

4. Custom Port: Change the port via environment variable:

   PORT=4000 npx tsx examples/simple.ts

🎓 Learning Path

We recommend exploring the examples in this order:

1. simple.ts → Learn the basics
2. basic.ts → Understand validation and error handling
3. custom-fastify.ts → Use your own Fastify instance
4. custom-auth.ts → Master authentication patterns

📖 More Information

For detailed API documentation, see the main README.md in the project root.