Creating New Resources with DTOs and Validation

Introduction: Creating New Resources in an API

Welcome to your first lesson in building the Reading Tracker API with NestJS! In this lesson, you will learn how to let users add new resources — specifically, new books — to your API. In the world of web APIs, a "resource" is just a piece of data, like a book, a user, or a review. When you want to add a new resource, you usually use a POST request. As a reminder, POST request is part of the HTTP protocol and is typically used when the client wants to send data to the server to create a new resource. In our case, the resource is a book. For example, if you want to let someone add a new book to your reading tracker, you would create a POST endpoint. This endpoint will accept information about the book (like its title and author) and store it in your system. This is a common pattern in almost every web application. By the end of this lesson, you will know how to: Define a DTO (Data Transfer Object) to validate input. Create a POST endpoint in a controller. Use the UUID library to generate unique IDs for new resources.

What Are UUIDs and Why Do We Need Them?

Every resource in your system (book, user, session) needs a unique identifier. Instead of using simple numbers like 1, 2, 3, we use UUIDs (Universally Unique Identifiers) . A UUID is a long, random-looking string such as: 550e8400-e29b-41d4-a716-446655440000 They are designed to be globally unique, so you can safely generate IDs without worrying about collisions. UUIDs are commonly used in APIs, databases, and distributed systems. In Node.js, we use the uuid library. Normally, you install it with: Shell npm install uuid But in the CodeSignal environment, everything is already pre-installed — so you’re ready to use it right away. TypeScript // src/database/mock-db.ts import { v4 as uuidv4 } from 'uuid'; export const users = [{ id: uuidv4(), name: 'Alice' }, { id: uuidv4(), name: 'Bob' },]; export const books = [{ id: uuidv4(), title: 'The Hobbit', author: 'J.R.R. Tolkien' }, { id: uuidv4(), title: 'Dune', author: 'Frank Herbert' },]; Every time we create a new user or book, uuidv4() generates a fresh, unique id.

What Is a DTO and Why It Matters

When someone sends data to your API (for example, to add a new book), you want to make sure the data is correct. This is where a Data Transfer Object (DTO) comes in. A DTO is a simple class that describes what data you expect and helps validate it. DTO stands for Data Transfer Object . It acts as a contract between the client (like a frontend or mobile app) and your API. When someone wants to send data to your server (like creating a book), they must follow the structure you define in the DTO. DTOs ensure: Your code knows exactly what shape of data to expect. Invalid or missing data is caught early before it breaks your business logic. The frontend and backend can evolve independently while maintaining agreed structure. To use these validation decorators, you need to install the validation libraries: Shell npm install class-validator class-transformer These libraries integrate with NestJS and automatically check incoming data before it reaches your service . If a request doesn’t pass validation (e.g., title is missing), NestJS returns a clear 400 Bad Request response — no manual checks required. Here’s an example DTO for creating a new book: TypeScript // src/books/dto/create-book.dto.ts import { IsString, IsNotEmpty } from 'class-validator'; export class CreateBookDto {@IsString() @IsNotEmpty() title!: string; @IsString() @IsNotEmpty() author!: string;} Explanation: @IsString() and @IsNotEmpty() are decorators from the class-validator library. They make sure that both title and author are non-empty strings. If someone tries to add a book without a title or author, or with numbers instead of text, the API will reject the request. This helps keep your data clean and your application safe from bad input.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Building a POST Endpoint with NestJS

Now, let’s see how to actually create a POST endpoint that uses this DTO. In NestJS, you use a controller to define your endpoints.

Here’s how you set up the POST endpoint for adding a new book:

TypeScript

// src/books/books.controller.ts
import { Controller, Post, Body, Get } from '@nestjs/common';
import { BooksService } from './books.service';
import { CreateBookDto } from './dto/create-book.dto';

@Controller('books')
export class BooksController {
  constructor(private readonly booksService: BooksService) {}
  
  @Post()
  create(@Body() createBookDto: CreateBookDto) {
    const book = this.booksService.create(createBookDto);
    return { success: true, data: book };
  }

  @Get()
  findAll() {
    const books = this.booksService.findAll();
    return { success: true, data: books };
  }
}

// src/books/books.controller.ts
import { Controller, Post, Body, Get } from '@nestjs/common';
import { BooksService } from './books.service';
import { CreateBookDto } from './dto/create-book.dto';

@Controller('books')
export class BooksController {
  constructor(private readonly booksService: BooksService) {}
  
  @Post()
  create(@Body() createBookDto: CreateBookDto) {
    const book = this.booksService.create(createBookDto);
    return { success: true, data: book };
  }

  @Get()
  findAll() {
    const books = this.booksService.findAll();
    return { success: true, data: books };
  }
}

Explanation:

@Controller('books') means all routes in this controller will start with /books.
@Post() creates a POST endpoint at /books.
@Body() createBookDto: CreateBookDto tells NestJS to take the request body, validate it using the CreateBookDto, and pass it to the create method.
The controller then calls the service to actually add the book.

NestJS automatically:

Transforms the incoming JSON payload into an instance of the CreateBookDto class.

Validates that it meets the required constraints defined in the class decorators.

Rejects the request with an error message if validation fails — you don’t need to write manual if (!title) checks anymore.

This is a powerful pattern that reduces repetitive error-checking code and ensures a consistent API structure.

Example Request:

JSON

POST /books
{
  "title": "The Hobbit",
  "author": "J.R.R. Tolkien"
}

POST /books
{
  "title": "The Hobbit",
  "author": "J.R.R. Tolkien"
}

If the data is valid, the book will be added. If not, the API will return an error.

How the Service Handles New Data

The controller passes the validated data to a service, which handles the logic of adding the new book to your database (in this case, an in-memory array).The service actually creates the new book and assigns it a UUID.

Here’s the service code:

TypeScript

// src/books/books.service.ts
import { Injectable } from '@nestjs/common';
import { DatabaseService } from '../database/database.service';
import { CreateBookDto } from './dto/create-book.dto';
import { v4 as uuidv4 } from 'uuid';

@Injectable()
export class BooksService {
  constructor(private readonly db: DatabaseService) {}

  create(createBookDto: CreateBookDto) {
    const newBook = {
      id: uuidv4(),   // generate unique ID
      ...createBookDto,
    };
    this.db.getBooks().push(newBook);
    return newBook;
  }
  
  findAll() {
    return this.db.getBooks();
  }
}

// src/books/books.service.ts
import { Injectable } from '@nestjs/common';
import { DatabaseService } from '../database/database.service';
import { CreateBookDto } from './dto/create-book.dto';
import { v4 as uuidv4 } from 'uuid';

@Injectable()
export class BooksService {
  constructor(private readonly db: DatabaseService) {}

  create(createBookDto: CreateBookDto) {
    const newBook = {
      id: uuidv4(),   // generate unique ID
      ...createBookDto,
    };
    this.db.getBooks().push(newBook);
    return newBook;
  }
  
  findAll() {
    return this.db.getBooks();
  }
}

Explanation:

The service gets the current list of books from the DatabaseService.
It creates a new book object, giving it a unique id.
The new book is added to the list and returned.

Example Request:

JSON

POST /books
{
"title": "Neuromancer",
"author": "William Gibson"
}

POST /books
{
"title": "Neuromancer",
"author": "William Gibson"
}

Example response:

JSON

{
  "success": true,
  "data": {
    "id": "e3a32cd5-9e6b-4b2c-a36c-0a5f4c0f4c2b",
    "title": "Neuromancer",
    "author": "William Gibson"
  }
}

{
  "success": true,
  "data": {
    "id": "e3a32cd5-9e6b-4b2c-a36c-0a5f4c0f4c2b",
    "title": "Neuromancer",
    "author": "William Gibson"
  }
}

This is what the client will see after successfully adding a book.

Introduction: Creating New Resources in an API

What Are UUIDs and Why Do We Need Them?

What Is a DTO and Why It Matters

Join the 1M+ learners on CodeSignal

Building a POST Endpoint with NestJS

How the Service Handles New Data

Why DTOs, UUIDs and Validation Are Critical in Real Projects

Summary and What’s Next