Skip to content

README.md

Latest commit

 

History

History
180 lines (119 loc) · 3.94 KB

README.md

File metadata and controls

180 lines (119 loc) · 3.94 KB

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.