📘 REST API Server: Complete CRUD Application

🎯 Introduction

Welcome to this exciting tutorial on building a complete REST API server with TypeScript! 🎉 In this guide, we’ll create a fully-functional CRUD (Create, Read, Update, Delete) application that you can use as a foundation for your own projects.

You’ll discover how TypeScript transforms backend development by providing type safety, better tooling, and cleaner code architecture. Whether you’re building a startup MVP 🚀, an enterprise API 🏢, or a personal project 💻, mastering TypeScript REST APIs is essential for modern web development.

By the end of this tutorial, you’ll have a production-ready API server with proper error handling, validation, and best practices! Let’s dive in! 🏊‍♂️

📚 Understanding REST APIs with TypeScript

🤔 What Makes a TypeScript REST API Special?

Building REST APIs with TypeScript is like having a safety net while performing trapeze acts 🎪. Think of it as having a helpful assistant who catches your mistakes before they cause problems in production!

In TypeScript terms, a REST API server combines HTTP endpoints with type-safe request/response handling. This means you can:

• ✨ Define exact shapes for request bodies and responses
• 🚀 Get autocomplete for API routes and middleware
• 🛡️ Catch errors during development, not in production
• 📖 Generate documentation from your types

💡 Why TypeScript for REST APIs?

Here’s why developers love TypeScript for backend development:

1. Type-Safe Routes 🔒: Know exactly what data flows through your API
2. Better Refactoring 💻: Change endpoints without fear of breaking clients
3. Self-Documenting Code 📖: Types serve as live documentation
4. Early Error Detection 🔧: Catch bugs before they reach production

Real-world example: Imagine building an e-commerce API 🛒. With TypeScript, you can ensure that product prices are always numbers, quantities are positive integers, and order statuses match your business logic!

🔧 Basic Syntax and Usage

📝 Setting Up Our TypeScript API Server

Let’s start with a friendly example using Express and TypeScript:

// 👋 Hello, REST API!
import express, { Request, Response } from 'express';

// 🎨 Creating our Express app
const app = express();
app.use(express.json()); // 📦 Parse JSON bodies

// 🎯 Define our data types
interface User {
  id: string;       // 🆔 Unique identifier  
  name: string;     // 👤 User's name
  email: string;    // 📧 Email address
  role: 'admin' | 'user'; // 🎭 User role
}

// 🗄️ In-memory database (for demo)
const users: User[] = [
  { id: '1', name: 'Alice', email: '[email protected]', role: 'admin' }
];

// 🚀 Your first endpoint!
app.get('/api/users', (req: Request, res: Response<User[]>) => {
  res.json(users);
});

// 🎉 Start the server
app.listen(3000, () => {
  console.log('🚀 Server running on http://localhost:3000');
});

💡 Explanation: Notice how we type our response with Response<User[]>! This ensures we always return the correct data shape.

🎯 CRUD Operations Pattern

Here’s the pattern for a complete CRUD API:

// 🏗️ Request/Response types
interface CreateUserDto {
  name: string;
  email: string;
  password: string;
}

interface UpdateUserDto {
  name?: string;
  email?: string;
}

interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: string;
}

// 🎨 CRUD endpoints
class UserController {
  // 📖 GET all users
  async getUsers(req: Request, res: Response<ApiResponse<User[]>>) {
    res.json({
      success: true,
      data: users
    });
  }
  
  // 🔍 GET single user
  async getUser(req: Request<{ id: string }>, res: Response<ApiResponse<User>>) {
    const user = users.find(u => u.id === req.params.id);
    
    if (!user) {
      return res.status(404).json({
        success: false,
        error: 'User not found 😞'
      });
    }
    
    res.json({
      success: true,
      data: user
    });
  }
  
  // ➕ POST create user
  async createUser(
    req: Request<{}, {}, CreateUserDto>, 
    res: Response<ApiResponse<User>>
  ) {
    const newUser: User = {
      id: Date.now().toString(),
      name: req.body.name,
      email: req.body.email,
      role: 'user'
    };
    
    users.push(newUser);
    
    res.status(201).json({
      success: true,
      data: newUser
    });
  }
}

💡 Practical Examples

🛒 Example 1: E-Commerce Product API

Let’s build a real product management API:

// 🛍️ Product management system
interface Product {
  id: string;
  name: string;
  price: number;
  stock: number;
  category: string;
  emoji: string; // Every product needs an emoji!
}

interface Order {
  id: string;
  userId: string;
  items: OrderItem[];
  total: number;
  status: 'pending' | 'processing' | 'shipped' | 'delivered';
  createdAt: Date;
}

interface OrderItem {
  productId: string;
  quantity: number;
  price: number;
}

// 🏪 Product service with validation
class ProductService {
  private products: Map<string, Product> = new Map();
  
  // ✨ Create product with validation
  async createProduct(data: Omit<Product, 'id'>): Promise<Product> {
    // 🛡️ Validate product data
    if (data.price < 0) {
      throw new Error('Price cannot be negative! 💸');
    }
    
    if (data.stock < 0) {
      throw new Error('Stock cannot be negative! 📦');
    }
    
    const product: Product = {
      ...data,
      id: `prod_${Date.now()}`
    };
    
    this.products.set(product.id, product);
    console.log(`✅ Created product: ${product.emoji} ${product.name}`);
    
    return product;
  }
  
  // 🔄 Update stock after order
  async updateStock(productId: string, quantity: number): Promise<void> {
    const product = this.products.get(productId);
    
    if (!product) {
      throw new Error('Product not found! 🔍');
    }
    
    if (product.stock < quantity) {
      throw new Error(`Insufficient stock! Only ${product.stock} available 😞`);
    }
    
    product.stock -= quantity;
    console.log(`📦 Updated stock for ${product.emoji} ${product.name}: ${product.stock} remaining`);
  }
}

// 🎯 Express routes with error handling
const productRouter = express.Router();
const productService = new ProductService();

// 🛍️ Create product endpoint
productRouter.post('/products', async (req, res) => {
  try {
    const product = await productService.createProduct(req.body);
    res.status(201).json({
      success: true,
      data: product,
      message: `Product created successfully! ${product.emoji}`
    });
  } catch (error) {
    res.status(400).json({
      success: false,
      error: error.message
    });
  }
});

// 🛒 Create order endpoint
productRouter.post('/orders', async (req, res) => {
  try {
    const { userId, items } = req.body;
    
    // 💰 Calculate total and check stock
    let total = 0;
    for (const item of items) {
      await productService.updateStock(item.productId, item.quantity);
      total += item.price * item.quantity;
    }
    
    const order: Order = {
      id: `order_${Date.now()}`,
      userId,
      items,
      total,
      status: 'pending',
      createdAt: new Date()
    };
    
    res.status(201).json({
      success: true,
      data: order,
      message: '🎉 Order placed successfully!'
    });
  } catch (error) {
    res.status(400).json({
      success: false,
      error: error.message
    });
  }
});

🎯 Try it yourself: Add a discount system and inventory alerts when stock is low!

🎮 Example 2: Task Management API with Authentication

Let’s make a secure task management system:

// 🔐 Authentication middleware
interface AuthRequest extends Request {
  user?: {
    id: string;
    email: string;
    role: string;
  };
}

// 📋 Task management types
interface Task {
  id: string;
  title: string;
  description: string;
  status: 'todo' | 'in-progress' | 'done';
  priority: 'low' | 'medium' | 'high';
  assigneeId: string;
  dueDate?: Date;
  tags: string[];
  emoji: string;
}

// 🛡️ Authentication middleware
const authenticate = (req: AuthRequest, res: Response, next: NextFunction) => {
  const token = req.headers.authorization?.split(' ')[1];
  
  if (!token) {
    return res.status(401).json({
      success: false,
      error: 'No token provided! 🔐'
    });
  }
  
  // 🎯 Verify token (simplified for demo)
  req.user = {
    id: '123',
    email: '[email protected]',
    role: 'user'
  };
  
  next();
};

// 📋 Task service with filtering
class TaskService {
  private tasks: Map<string, Task> = new Map();
  
  // 🎯 Get tasks with filters
  async getUserTasks(
    userId: string, 
    filters?: {
      status?: Task['status'];
      priority?: Task['priority'];
      search?: string;
    }
  ): Promise<Task[]> {
    const userTasks = Array.from(this.tasks.values())
      .filter(task => task.assigneeId === userId);
    
    if (!filters) return userTasks;
    
    return userTasks.filter(task => {
      if (filters.status && task.status !== filters.status) return false;
      if (filters.priority && task.priority !== filters.priority) return false;
      if (filters.search && !task.title.toLowerCase().includes(filters.search.toLowerCase())) return false;
      return true;
    });
  }
  
  // 📊 Get task statistics
  async getTaskStats(userId: string): Promise<{
    total: number;
    byStatus: Record<Task['status'], number>;
    byPriority: Record<Task['priority'], number>;
    overdue: number;
  }> {
    const tasks = await this.getUserTasks(userId);
    const now = new Date();
    
    const stats = {
      total: tasks.length,
      byStatus: { 'todo': 0, 'in-progress': 0, 'done': 0 },
      byPriority: { 'low': 0, 'medium': 0, 'high': 0 },
      overdue: 0
    };
    
    tasks.forEach(task => {
      stats.byStatus[task.status]++;
      stats.byPriority[task.priority]++;
      if (task.dueDate && task.dueDate < now && task.status !== 'done') {
        stats.overdue++;
      }
    });
    
    return stats;
  }
}

// 🚀 Task routes with authentication
const taskRouter = express.Router();
const taskService = new TaskService();

// 🔐 All routes require authentication
taskRouter.use(authenticate);

// 📋 Get user's tasks with filters
taskRouter.get('/tasks', async (req: AuthRequest, res) => {
  const tasks = await taskService.getUserTasks(
    req.user!.id,
    {
      status: req.query.status as Task['status'],
      priority: req.query.priority as Task['priority'],
      search: req.query.search as string
    }
  );
  
  res.json({
    success: true,
    data: tasks,
    count: tasks.length
  });
});

// 📊 Get task statistics
taskRouter.get('/tasks/stats', async (req: AuthRequest, res) => {
  const stats = await taskService.getTaskStats(req.user!.id);
  
  res.json({
    success: true,
    data: stats,
    message: stats.overdue > 0 ? `⚠️ You have ${stats.overdue} overdue tasks!` : '✅ All tasks on track!'
  });
});

🚀 Advanced Concepts

🧙‍♂️ Advanced Topic 1: Request Validation with Decorators

When you’re ready to level up, try this advanced validation pattern:

// 🎯 Custom validation decorators
import { body, validationResult } from 'express-validator';

// 🪄 Validation middleware factory
const validate = (validations: any[]) => {
  return async (req: Request, res: Response, next: NextFunction) => {
    await Promise.all(validations.map(validation => validation.run(req)));
    
    const errors = validationResult(req);
    if (!errors.isEmpty()) {
      return res.status(400).json({
        success: false,
        errors: errors.array(),
        message: 'Validation failed! 😞'
      });
    }
    
    next();
  };
};

// ✨ Typed validation rules
const userValidation = {
  create: [
    body('name').isLength({ min: 2 }).withMessage('Name too short! 📏'),
    body('email').isEmail().withMessage('Invalid email! 📧'),
    body('password').isLength({ min: 8 }).withMessage('Password too weak! 🔐')
  ],
  update: [
    body('name').optional().isLength({ min: 2 }),
    body('email').optional().isEmail()
  ]
};

// 🚀 Using validation in routes
app.post('/api/users', 
  validate(userValidation.create),
  async (req, res) => {
    // Request is validated! ✅
    const user = await createUser(req.body);
    res.json({ success: true, data: user });
  }
);

🏗️ Advanced Topic 2: Type-Safe Error Handling

For the brave developers, here’s production-ready error handling:

// 🚀 Custom error classes
class ApiError extends Error {
  constructor(
    public statusCode: number,
    public message: string,
    public code?: string
  ) {
    super(message);
  }
}

class ValidationError extends ApiError {
  constructor(message: string, public fields?: Record<string, string>) {
    super(400, message, 'VALIDATION_ERROR');
  }
}

class NotFoundError extends ApiError {
  constructor(resource: string) {
    super(404, `${resource} not found! 🔍`, 'NOT_FOUND');
  }
}

// 🛡️ Global error handler
const errorHandler = (
  err: Error,
  req: Request,
  res: Response,
  next: NextFunction
) => {
  if (err instanceof ApiError) {
    return res.status(err.statusCode).json({
      success: false,
      error: err.message,
      code: err.code
    });
  }
  
  // 💥 Unexpected error
  console.error('Unexpected error:', err);
  res.status(500).json({
    success: false,
    error: 'Something went wrong! 😱',
    code: 'INTERNAL_ERROR'
  });
};

// 🎯 Using in async route handlers
const asyncHandler = (fn: Function) => (req: Request, res: Response, next: NextFunction) => {
  Promise.resolve(fn(req, res, next)).catch(next);
};

app.get('/api/users/:id', asyncHandler(async (req, res) => {
  const user = await userService.findById(req.params.id);
  if (!user) {
    throw new NotFoundError('User');
  }
  res.json({ success: true, data: user });
}));

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: Forgetting to Type Request Bodies

// ❌ Wrong way - no type safety for body!
app.post('/api/users', (req, res) => {
  const user = req.body; // 😰 What's in here?
  users.push(user); // 💥 Runtime error possible!
});

// ✅ Correct way - full type safety!
interface CreateUserBody {
  name: string;
  email: string;
  password: string;
}

app.post('/api/users', (req: Request<{}, {}, CreateUserBody>, res) => {
  const { name, email, password } = req.body; // 🛡️ Type-safe!
  // TypeScript knows exactly what's available
});

🤯 Pitfall 2: Not Handling Async Errors

// ❌ Dangerous - unhandled promise rejection!
app.get('/api/data', async (req, res) => {
  const data = await fetchData(); // 💥 If this throws, server crashes!
  res.json(data);
});

// ✅ Safe - proper error handling!
app.get('/api/data', async (req, res, next) => {
  try {
    const data = await fetchData();
    res.json({ success: true, data });
  } catch (error) {
    next(error); // 🛡️ Pass to error handler
  }
});

🛠️ Best Practices

1. 🎯 Use DTOs: Define Data Transfer Objects for requests/responses
2. 📝 Type Everything: Don’t use any - be specific with types
3. 🛡️ Validate Input: Always validate incoming data
4. 🎨 Consistent Structure: Use the same response format everywhere
5. ✨ Handle Errors Gracefully: Never expose internal errors to clients

🧪 Hands-On Exercise

🎯 Challenge: Build a Blog API

Create a type-safe blog API with these features:

📋 Requirements:

• ✅ Posts with title, content, author, tags
• 🏷️ Categories for organizing posts
• 👤 User authentication with roles
• 📅 Publishing schedule with drafts
• 🎨 Each post needs a cover emoji!

🚀 Bonus Points:

• Add comment system with nested replies
• Implement search with filters
• Create analytics endpoints

💡 Solution

// 🎯 Our type-safe blog system!
interface BlogPost {
  id: string;
  title: string;
  content: string;
  excerpt: string;
  authorId: string;
  categoryId: string;
  tags: string[];
  coverEmoji: string;
  status: 'draft' | 'published' | 'scheduled';
  publishDate?: Date;
  createdAt: Date;
  updatedAt: Date;
}

interface Comment {
  id: string;
  postId: string;
  authorId: string;
  content: string;
  parentId?: string; // For nested comments
  createdAt: Date;
}

class BlogService {
  private posts: Map<string, BlogPost> = new Map();
  private comments: Map<string, Comment> = new Map();
  
  // 📝 Create post with validation
  async createPost(
    data: Omit<BlogPost, 'id' | 'createdAt' | 'updatedAt'>,
    authorId: string
  ): Promise<BlogPost> {
    const post: BlogPost = {
      ...data,
      id: `post_${Date.now()}`,
      authorId,
      createdAt: new Date(),
      updatedAt: new Date()
    };
    
    this.posts.set(post.id, post);
    console.log(`✅ Created post: ${post.coverEmoji} ${post.title}`);
    
    return post;
  }
  
  // 🔍 Search posts with filters
  async searchPosts(filters: {
    query?: string;
    category?: string;
    tags?: string[];
    status?: BlogPost['status'];
  }): Promise<BlogPost[]> {
    return Array.from(this.posts.values()).filter(post => {
      if (filters.query && !post.title.toLowerCase().includes(filters.query.toLowerCase())) {
        return false;
      }
      if (filters.category && post.categoryId !== filters.category) {
        return false;
      }
      if (filters.tags?.length && !filters.tags.some(tag => post.tags.includes(tag))) {
        return false;
      }
      if (filters.status && post.status !== filters.status) {
        return false;
      }
      return true;
    });
  }
  
  // 💬 Add comment with nesting
  async addComment(
    postId: string,
    content: string,
    authorId: string,
    parentId?: string
  ): Promise<Comment> {
    const post = this.posts.get(postId);
    if (!post) {
      throw new Error('Post not found! 📝');
    }
    
    const comment: Comment = {
      id: `comment_${Date.now()}`,
      postId,
      authorId,
      content,
      parentId,
      createdAt: new Date()
    };
    
    this.comments.set(comment.id, comment);
    return comment;
  }
  
  // 📊 Get post analytics
  async getPostAnalytics(postId: string): Promise<{
    views: number;
    comments: number;
    avgReadTime: number;
    engagement: string;
  }> {
    const comments = Array.from(this.comments.values())
      .filter(c => c.postId === postId);
    
    return {
      views: Math.floor(Math.random() * 1000), // Simulated
      comments: comments.length,
      avgReadTime: 5, // minutes
      engagement: comments.length > 10 ? '🔥 Hot!' : '🌱 Growing'
    };
  }
}

// 🚀 Express routes
const blogRouter = express.Router();
const blogService = new BlogService();

// 📝 Create post
blogRouter.post('/posts', authenticate, async (req: AuthRequest, res) => {
  try {
    const post = await blogService.createPost(req.body, req.user!.id);
    res.status(201).json({
      success: true,
      data: post,
      message: `Post created! ${post.coverEmoji}`
    });
  } catch (error) {
    res.status(400).json({
      success: false,
      error: error.message
    });
  }
});

// 🔍 Search posts
blogRouter.get('/posts/search', async (req, res) => {
  const posts = await blogService.searchPosts({
    query: req.query.q as string,
    category: req.query.category as string,
    tags: req.query.tags ? (req.query.tags as string).split(',') : undefined,
    status: req.query.status as BlogPost['status']
  });
  
  res.json({
    success: true,
    data: posts,
    count: posts.length
  });
});

🎓 Key Takeaways

You’ve learned so much! Here’s what you can now do:

• ✅ Create REST APIs with full TypeScript support 💪
• ✅ Handle CRUD operations with type safety 🛡️
• ✅ Implement authentication and authorization 🔐
• ✅ Validate requests and handle errors properly 🐛
• ✅ Build production-ready API servers! 🚀

Remember: TypeScript makes your APIs more reliable, maintainable, and developer-friendly! 🤝

🤝 Next Steps

Congratulations! 🎉 You’ve mastered building REST API servers with TypeScript!

Here’s what to do next:

1. 💻 Build the blog API from the exercise
2. 🏗️ Add database integration (PostgreSQL, MongoDB)
3. 📚 Learn about GraphQL with TypeScript
4. 🌟 Deploy your API to production!

Remember: Every great API started with a single endpoint. Keep building, keep learning, and most importantly, have fun! 🚀

Happy coding! 🎉🚀✨