Getting Started with NestJS - Build Your First REST API

#Introduction

NestJS has become the go-to framework for building scalable backend applications in the Node.js ecosystem. If you're coming from Express or Fastify, you might wonder what makes NestJS different. The answer lies in its opinionated architecture, built-in dependency injection, and TypeScript-first approach that makes your codebase maintainable and testable from day one.

In this guide, we'll build a real project—a task management API—that demonstrates NestJS fundamentals. You'll understand how modules, controllers, services, and decorators work together to create clean, production-grade code.

#Table of Contents

#Why NestJS?

Before diving into code, let's understand why NestJS matters. Traditional Express applications often become messy as they scale. NestJS enforces structure through its modular architecture, inspired by Angular. This means:

Dependency Injection: Automatic wiring of dependencies reduces boilerplate
Decorators: Clean, readable syntax for routing and validation
TypeScript Support: First-class TypeScript support with strict typing
Testing: Built-in testing utilities and patterns
Scalability: Designed for large teams and complex applications

#Setting Up Your First NestJS Project

#Installation

The fastest way to start is using the NestJS CLI:

Install NestJS CLI

npm install -g @nestjs/cli

Create a new project:

Create a new NestJS project

nest new task-api
cd task-api

The CLI generates a complete project structure with everything you need. Let's verify the setup works:

Start the development server

npm run start:dev

Visit http://localhost:3000 and you should see Hello World!. That's your first NestJS app running.

#Project Structure

plaintext

task-api/
├── src/
│   ├── app.controller.ts
│   ├── app.module.ts
│   ├── app.service.ts
│   └── main.ts
├── test/
├── package.json
├── tsconfig.json
└── nest-cli.json

Each file serves a purpose:

main.ts: Application entry point
app.module.ts: Root module that organizes your app
app.controller.ts: Handles HTTP requests
app.service.ts: Contains business logic

#Core Concepts

#Modules

Modules are containers that organize related functionality. Think of them as feature domains. A module can have controllers, services, and other modules as dependencies.

app.module.ts

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
 
@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

The @Module decorator defines:

imports: Other modules this module depends on
controllers: Request handlers
providers: Services and other injectable classes

#Controllers

Controllers handle incoming HTTP requests and return responses. They use decorators to define routes and HTTP methods.

app.controller.ts

import { Controller, Get, Post, Body, Param } from '@nestjs/common';
import { AppService } from './app.service';
 
@Controller('tasks')
export class AppController {
  constructor(private readonly appService: AppService) {}
 
  @Get()
  getAllTasks() {
    return this.appService.getAllTasks();
  }
 
  @Post()
  createTask(@Body() createTaskDto: any) {
    return this.appService.createTask(createTaskDto);
  }
 
  @Get(':id')
  getTaskById(@Param('id') id: string) {
    return this.appService.getTaskById(id);
  }
}

Key decorators:

@Controller('tasks'): Base route for all methods in this controller
@Get(), @Post(): HTTP method decorators
@Body(): Extract request body
@Param(): Extract URL parameters

#Services

Services contain business logic and are reusable across controllers. They're injected via the constructor.

app.service.ts

import { Injectable } from '@nestjs/common';
 
@Injectable()
export class AppService {
  private tasks = [
    { id: 1, title: 'Learn NestJS', completed: false },
    { id: 2, title: 'Build an API', completed: false },
  ];
 
  getAllTasks() {
    return this.tasks;
  }
 
  createTask(createTaskDto: any) {
    const newTask = {
      id: this.tasks.length + 1,
      ...createTaskDto,
      completed: false,
    };
    this.tasks.push(newTask);
    return newTask;
  }
 
  getTaskById(id: string) {
    return this.tasks.find(task => task.id === parseInt(id));
  }
}

The @Injectable() decorator marks a class as a provider that can be injected into other classes.

#Building the Task Management API

Now let's build a complete task API with proper structure. We'll create a dedicated tasks module.

#Generate the Tasks Module

Generate tasks module

nest generate module tasks
nest generate controller tasks
nest generate service tasks

This creates the module structure automatically:

plaintext

src/
├── tasks/
│   ├── tasks.module.ts
│   ├── tasks.controller.ts
│   └── tasks.service.ts

#Create a DTO (Data Transfer Object)

DTOs define the shape of data coming in and going out. Create src/tasks/dto/create-task.dto.ts:

create-task.dto.ts

export class CreateTaskDto {
  title: string;
  description?: string;
}

#Implement the Tasks Service

tasks.service.ts

import { Injectable, NotFoundException } from '@nestjs/common';
import { CreateTaskDto } from './dto/create-task.dto';
 
interface Task {
  id: number;
  title: string;
  description?: string;
  completed: boolean;
  createdAt: Date;
}
 
@Injectable()
export class TasksService {
  private tasks: Task[] = [];
  private idCounter = 1;
 
  create(createTaskDto: CreateTaskDto): Task {
    const task: Task = {
      id: this.idCounter++,
      ...createTaskDto,
      completed: false,
      createdAt: new Date(),
    };
    this.tasks.push(task);
    return task;
  }
 
  findAll(): Task[] {
    return this.tasks;
  }
 
  findOne(id: number): Task {
    const task = this.tasks.find(t => t.id === id);
    if (!task) {
      throw new NotFoundException(`Task with ID ${id} not found`);
    }
    return task;
  }
 
  update(id: number, updateTaskDto: Partial<CreateTaskDto>): Task {
    const task = this.findOne(id);
    Object.assign(task, updateTaskDto);
    return task;
  }
 
  remove(id: number): void {
    const index = this.tasks.findIndex(t => t.id === id);
    if (index === -1) {
      throw new NotFoundException(`Task with ID ${id} not found`);
    }
    this.tasks.splice(index, 1);
  }
 
  toggleComplete(id: number): Task {
    const task = this.findOne(id);
    task.completed = !task.completed;
    return task;
  }
}

#Implement the Tasks Controller

tasks.controller.ts

import {
  Controller,
  Get,
  Post,
  Body,
  Param,
  Delete,
  Patch,
  ParseIntPipe,
} from '@nestjs/common';
import { TasksService } from './tasks.service';
import { CreateTaskDto } from './dto/create-task.dto';
 
@Controller('tasks')
export class TasksController {
  constructor(private readonly tasksService: TasksService) {}
 
  @Post()
  create(@Body() createTaskDto: CreateTaskDto) {
    return this.tasksService.create(createTaskDto);
  }
 
  @Get()
  findAll() {
    return this.tasksService.findAll();
  }
 
  @Get(':id')
  findOne(@Param('id', ParseIntPipe) id: number) {
    return this.tasksService.findOne(id);
  }
 
  @Patch(':id')
  update(
    @Param('id', ParseIntPipe) id: number,
    @Body() updateTaskDto: Partial<CreateTaskDto>,
  ) {
    return this.tasksService.update(id, updateTaskDto);
  }
 
  @Delete(':id')
  remove(@Param('id', ParseIntPipe) id: number) {
    this.tasksService.remove(id);
    return { message: 'Task deleted successfully' };
  }
 
  @Patch(':id/toggle')
  toggleComplete(@Param('id', ParseIntPipe) id: number) {
    return this.tasksService.toggleComplete(id);
  }
}

Notice ParseIntPipe—it automatically converts the string parameter to an integer and validates it.

#Update the Tasks Module

tasks.module.ts

import { Module } from '@nestjs/common';
import { TasksService } from './tasks.service';
import { TasksController } from './tasks.controller';
 
@Module({
  controllers: [TasksController],
  providers: [TasksService],
})
export class TasksModule {}

#Import Tasks Module in App Module

app.module.ts

import { Module } from '@nestjs/common';
import { TasksModule } from './tasks/tasks.module';
 
@Module({
  imports: [TasksModule],
})
export class AppModule {}

#Testing Your API

Start the development server:

Start development server

npm run start:dev

Use curl or a tool like Bruno/Postman to test:

curl -X POST http://localhost:3000/tasks \
  -H "Content-Type: application/json" \
  -d '{"title":"Learn NestJS","description":"Complete the tutorial"}'

#Common Mistakes & Pitfalls

#Forgetting to Inject Services

Services must be declared in the module's providers array and injected via constructor. Forgetting either step causes runtime errors.

❌ Wrong - Service not provided

@Module({
  controllers: [TasksController],
  // Missing TasksService in providers
})
export class TasksModule {}

✅ Correct - Service properly provided

@Module({
  controllers: [TasksController],
  providers: [TasksService],
})
export class TasksModule {}

#Not Using DTOs

Accepting any type defeats TypeScript's benefits. Always define DTOs for type safety and validation.

❌ Wrong - No type safety

@Post()
create(@Body() data: any) {
  return this.tasksService.create(data);
}

✅ Correct - Typed DTO

@Post()
create(@Body() createTaskDto: CreateTaskDto) {
  return this.tasksService.create(createTaskDto);
}

#Mixing Business Logic in Controllers

Controllers should only handle HTTP concerns. Business logic belongs in services.

❌ Wrong - Logic in controller

@Get()
findAll() {
  const tasks = this.tasks.filter(t => !t.completed);
  return tasks.sort((a, b) => a.id - b.id);
}

✅ Correct - Logic in service

// In service
findAllPending(): Task[] {
  return this.tasks
    .filter(t => !t.completed)
    .sort((a, b) => a.id - b.id);
}
 
// In controller
@Get('pending')
findAllPending() {
  return this.tasksService.findAllPending();
}

#Best Practices

#Use Validation Pipes

Install class-validator and class-transformer:

Update your DTO with validation decorators:

create-task.dto.ts with validation

import { IsString, IsOptional, MinLength } from 'class-validator';
 
export class CreateTaskDto {
  @IsString()
  @MinLength(3)
  title: string;
 
  @IsOptional()
  @IsString()
  description?: string;
}

Enable global validation in main.ts:

main.ts

import { NestFactory } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';
import { AppModule } from './app.module';
 
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalPipes(new ValidationPipe());
  await app.listen(3000);
}
bootstrap();

#Organize by Feature

Structure your project by features, not by type:

plaintext

src/
├── tasks/
│   ├── dto/
│   ├── tasks.controller.ts
│   ├── tasks.service.ts
│   └── tasks.module.ts
├── users/
│   ├── dto/
│   ├── users.controller.ts
│   ├── users.service.ts
│   └── users.module.ts
└── app.module.ts

This makes it easy to find related code and scale your application.

#Handle Errors Gracefully

Use NestJS built-in exceptions:

Error handling in service

import { NotFoundException, BadRequestException } from '@nestjs/common';
 
findOne(id: number): Task {
  if (id <= 0) {
    throw new BadRequestException('ID must be a positive number');
  }
  const task = this.tasks.find(t => t.id === id);
  if (!task) {
    throw new NotFoundException(`Task with ID ${id} not found`);
  }
  return task;
}

#Write Tests

NestJS comes with Jest pre-configured. Create tasks.service.spec.ts:

tasks.service.spec.ts

import { Test, TestingModule } from '@nestjs/testing';
import { TasksService } from './tasks.service';
 
describe('TasksService', () => {
  let service: TasksService;
 
  beforeEach(async () => {
    const module: TestingModule = await Test.createTestingModule({
      providers: [TasksService],
    }).compile();
 
    service = module.get<TasksService>(TasksService);
  });
 
  it('should create a task', () => {
    const result = service.create({ title: 'Test Task' });
    expect(result.title).toBe('Test Task');
    expect(result.completed).toBe(false);
  });
 
  it('should find all tasks', () => {
    service.create({ title: 'Task 1' });
    service.create({ title: 'Task 2' });
    expect(service.findAll()).toHaveLength(2);
  });
});

Run tests with:

Run tests

npm run test

#When NOT to Use NestJS

NestJS is powerful but not always the right choice:

Simple scripts or CLI tools: Overkill for small utilities
Real-time applications: Consider Fastify or raw Node.js for ultra-low latency
Microservices at scale: You might need more specialized frameworks
Learning Node.js basics: Start with Express to understand fundamentals first

For most REST APIs, GraphQL servers, and backend services, NestJS is an excellent choice.

#Conclusion

You now have a working task management API built with NestJS. You've learned about modules, controllers, services, dependency injection, and best practices. The architecture you've built scales from a small project to an enterprise application.

Next steps: explore NestJS documentation on databases (TypeORM, Prisma), authentication, and middleware. The patterns you've learned here apply to all NestJS projects.

Start building, and you'll quickly see why NestJS has become the framework of choice for serious Node.js backend development.

Getting Started with NestJS - Build Your First REST API

Related Posts