DEV Community: Javier Vega

Basic REST API with NestJS 2025

Javier Vega — Sun, 16 Feb 2025 04:54:21 +0000

Basic REST API with NestJS 2025

In this tutorial, I will show you how to develop a basic REST API using NestJS.

Requirements review

Now, suppose you are given the following database design:

You are required to create a REST API with the following endpoints:

Products:

Method	Endpoint	Description
GET	/api/products	Get paginated list of products
GET	/api/products/{id}	Get a specific product by ID
POST	/api/products	Create a new product
PUT	/api/products/{id}	Update an existing product
DELETE	/api/products/{id}	Delete a product

Categories:

Method	Endpoint	Description
GET	/api/categories	Get paginated list of categories
GET	/api/categories/{id}	Get a specific category by ID
POST	/api/categories	Create a new category
PUT	/api/categories/{id}	Update an existing category
DELETE	/api/categories/{id}	Delete a category

Example of responses:
GET /api/products

{
  "content": [
    {
      "id": 1,
      "name": "Smartphone X",
      "description": "A high-end smartphone with an excellent camera.",
      "price": 999.99,
      "categories": [
        {
          "id": 2,
          "name": "Electronics"
        },
        {
          "id": 5,
          "name": "Mobile Phones"
        }
      ]
    }
  ],
  "pageNo": 0,
  "pageSize": 10,
  "totalElements": 1,
  "totalPages": 1,
  "last": true
}

GET /api/products/{id}

{
  "id": 1,
  "name": "Smartphone X",
  "description": "A high-end smartphone with an excellent camera.",
  "price": 999.99,
  "categories": [
    {
      "id": 2,
      "name": "Electronics"
    },
    {
      "id": 5,
      "name": "Mobile Phones"
    }
  ]
}

POST /api/products

// Body
{
  "name": "Smartwatch Z",
  "description": "A waterproof smartwatch with fitness tracking.",
  "price": 199.99,
  "categories": [2, 7]
}

// Response
{
  "id": 2,
  "name": "Smartwatch Z",
  "description": "A waterproof smartwatch with fitness tracking.",
  "price": 199.99,
  "categories": [
    {
      "id": 2,
      "name": "Electronics"
    },
    {
      "id": 7,
      "name": "Wearables"
    }
  ]
}

PUT /api/products/{id}

// Body
{
  "name": "Smartwatch Z Pro",
  "description": "Upgraded smartwatch with longer battery life.",
  "price": 249.99,
  "categories": [2, 7]
}

// Response
{
  "id": 2,
  "name": "Smartwatch Z Pro",
  "description": "Upgraded smartwatch with longer battery life.",
  "price": 249.99,
  "categories": [
    {
      "id": 2,
      "name": "Electronics"
    },
    {
      "id": 7,
      "name": "Wearables"
    }
  ]
}

DELETE /api/products/{id}

{
  "message": "Product deleted successfully"
}

The database must be implemented using PostgreSQL.

Database

If you don't have a PostgreSQL database, install Docker on your computer and use the file docker-compose.local-dev.yaml
to create a PostgreSQL server and a database.

Add a file .env in the root of the project with the following content:

# App
PORT=3000
CLIENT_URL="http://localhost:5173"

# DB Postgress
POSTGRES_DB_NAME=products-api
POSTGRES_DB_HOST=localhost
POSTGRES_DB_PORT=5432
POSTGRES_DB_USERNAME=admin
POSTGRES_DB_PASSWORD=admin

Then run this command in the root of the project:

docker compose -f docker-compose.local-dev.yaml up -d

Start coding

Project setup

Install NestJS:

npm i -g @nestjs/cli

Create the project with this command:

nest new products-api

Select the package manager you want to use, I will use npm:

Which package manager would you ❤️ to use? npm

This command will create a folder products-api with a minimal NestJS project.

Now we can install the dependencies:

npm ci

And run the project:

npm run start

The app will be up and running on port 3000.

You can test the endpoints using Postman or the REST Client extension in VSCode

I will use the REST Client extension:

In the root of the project add a folder rest-client. Inside it add a file products.http and place this content:

@base_url=http://localhost:3000

# Get all products

GET {{base_url}}

You will see something like this:

Project directory structure

Create the following folders inside src:

core
database
products
categories

Project configuration

Database

Install the following packages:

npm install @nestjs/typeorm typeorm pg @nestjs/config

pg: Driver for communicating our NestJS app with the PostgreSQL database.
typeorm: Object Relational Mapper (ORM) for TypeScript.
@nestjs/typeorm: Package provided by NestJS to integrate TypeORM in our app.
@nestjs/config: Package provided by NestJS to use environment variables.

Create the following files inside the folder /database/ and paste the content:

/entities/base.ts:

import {
  CreateDateColumn,
  DeleteDateColumn,
  PrimaryGeneratedColumn,
  UpdateDateColumn,
} from 'typeorm';

export abstract class BaseModel {
  @PrimaryGeneratedColumn()
  id: number;

  @CreateDateColumn({
    name: 'created_at',
    type: 'timestamptz',
    default: () => 'CURRENT_TIMESTAMP',
  })
  createdAt: Date;

  @UpdateDateColumn({
    name: 'updated_at',
    type: 'timestamptz',
    default: () => 'CURRENT_TIMESTAMP',
    onUpdate: 'CURRENT_TIMESTAMP',
  })
  updatedAt: Date;

  @DeleteDateColumn({
    name: 'deleted_at',
    type: 'timestamptz',
  })
  deletedAt: Date;
}

/entities/product.ts:

import { BaseModel } from '@src/database/entities/base';
import { Entity, Column, ManyToMany, JoinTable } from 'typeorm';
import { Category } from './category';

@Entity({ name: 'products' })
export class Product extends BaseModel {
  @Column()
  name: string;

  @Column()
  description: string;

  @Column('decimal', { precision: 10, scale: 2 })
  price: number;

  @ManyToMany(() => Category, (category) => category.products, {
    cascade: true,
  })
  @JoinTable({
    name: 'product_categories',
    joinColumn: { name: 'product_id', referencedColumnName: 'id' },
    inverseJoinColumn: { name: 'category_id', referencedColumnName: 'id' },
  })
  categories: Category[];
}

/entities/category.ts:

import { BaseModel } from '@src/database/entities/base';
import { Entity, Column, ManyToMany } from 'typeorm';
import { Product } from './product';

@Entity({ name: 'categories' })
export class Category extends BaseModel {
  @Column()
  name: string;

  @ManyToMany(() => Product, (product) => product.categories)
  products: Product[];
}

/providers/postgresql.provider.ts:

import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { TypeOrmModuleOptions, TypeOrmOptionsFactory } from '@nestjs/typeorm';
import { Product } from '@src/database/entities/product';
import { Category } from '../entities/category';

@Injectable()
export class PostgresqlDdProvider implements TypeOrmOptionsFactory {
  constructor(private readonly configService: ConfigService) {}

  createTypeOrmOptions(): Promise<TypeOrmModuleOptions> | TypeOrmModuleOptions {
    return {
      type: 'postgres',
      host: this.configService.get<'string'>('POSTGRES_DB_HOST'),
      port: parseInt(
        this.configService.get<'string'>('POSTGRES_DB_PORT') ?? '5432',
      ),
      username: this.configService.get<'string'>('POSTGRES_DB_USERNAME'),
      password: this.configService.get<'string'>('POSTGRES_DB_PASSWORD'),
      database: this.configService.get<'string'>('POSTGRES_DB_NAME'),
      entities: [Product, Category],
      synchronize: true,
      logging: false,
    };
  }
}

/database.module.ts:

import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';

import { PostgresqlDdProvider } from './providers/postgresql.provider';

@Module({
  imports: [
    TypeOrmModule.forRootAsync({
      name: 'postgres', // Explicitly set the connection name for PostgreSQL
      useClass: PostgresqlDdProvider,
    }),
  ],
  exports: [TypeOrmModule],
})
export class DatabaseModule {}

Core

Delete files:

app.service.ts
app.controller.ts
app.controller.spec.ts

Install the following packages:

npm install helmet nestjs-pino @nestjs/throttler

npm install pino-pretty --save-dev

helmet: Middleware that enhances security by setting various HTTP headers.
nestjs-pino: Logging integration for NestJS that uses the pino logger. Pino is a fast and efficient logging library for Node.js.
@nestjs/throttler: NestJS module that provides rate-limiting functionality for your application.
pino-pretty: Formats Pino's structured JSON logs into a human-readable, colorized output for easier debugging in development.

Replace the content in main.ts with the following:

import { NestFactory } from '@nestjs/core';
import { ValidationPipe, Logger } from '@nestjs/common';

import { Logger as PinoLogger } from 'nestjs-pino';
import helmet from 'helmet';

import { AppModule } from './app.module';

import * as bodyParser from 'body-parser';

async function bootstrap() {
  const app = await NestFactory.create(AppModule, {
    bufferLogs: true,
    bodyParser: true,
  });

  // Increase payload size limit
  app.use(bodyParser.json({ limit: '10mb' }));
  app.use(bodyParser.urlencoded({ limit: '10mb', extended: true }));

  app.useLogger(app.get(PinoLogger));

  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true,
      forbidNonWhitelisted: true,
      transform: true,
    }),
  );

  app.use(helmet());

  app.enableCors({
    origin: process.env.CLIENT_URL ?? '*',
    credentials: true,
  });

  await app.listen(process.env.PORT ?? 3000);

  const logger = new Logger('Bootstrap');

  logger.log(`App is running on ${await app.getUrl()}`);
}

bootstrap();

Replace the content in app.module.ts with the following:

import { Module } from '@nestjs/common';

import { CoreModule } from './core/core.module';
import { ProductsModule } from './products/products.module';
import { CategoriesModule } from './categories/categories.module';

@Module({
  imports: [CoreModule, ProductsModule, CategoriesModule],
})
export class AppModule {}

Create the following file inside the folder /core/ and paste the content:

/core/core.module.ts:

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { ThrottlerModule } from '@nestjs/throttler';

import { LoggerModule } from 'nestjs-pino';

import { DatabaseModule } from '@src/database/database.module';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),

    ThrottlerModule.forRoot([
      {
        ttl: 60000, // Time-to-live in milliseconds
        limit: 60, // Maximum requests per window globally
      },
    ]),

    LoggerModule.forRoot({
      pinoHttp: {
        serializers: {
          req: () => undefined,
          res: () => undefined,
        },
        autoLogging: false,
        level: process.env.NODE_ENV === 'production' ? 'info' : 'debug',
        transport:
          process.env.NODE_ENV === 'production'
            ? undefined
            : {
                target: 'pino-pretty',
                options: {
                  messageKey: 'message',
                  colorize: true,
                },
              },
        messageKey: 'message',
      },
    }),

    DatabaseModule,
  ],
})
export class CoreModule {}

Products

Install the following packages:

npm install class-validator class-transformer

class-validator: Package that provides decorators and functions to validate the properties of classes, ensuring that the data meets specified rules. I will use it in DTOs.
class-transformer: Transforms plain JavaScript objects into class instances and vice versa, enabling serialization and deserialization in TypeScript.

Create the following files inside the folder /products/ and paste the content:

/dtos/create-product.dto.ts:

import { ArrayNotEmpty, IsArray, IsNumber, IsString } from 'class-validator';

export class CreateProductDto {
  @IsString()
  name: string;

  @IsString()
  description: string;

  @IsNumber()
  price: number;

  @IsArray()
  @ArrayNotEmpty()
  @IsNumber({}, { each: true })
  categories: number[];
}

/dtos/update-product.dto.ts:

import { IsArray, IsNumber, IsOptional, IsString } from 'class-validator';

export class UpdateProductDto {
  @IsOptional()
  @IsString()
  name?: string;

  @IsOptional()
  @IsString()
  description?: string;

  @IsOptional()
  @IsNumber()
  price?: number;

  @IsOptional()
  @IsArray()
  @IsNumber({}, { each: true })
  categories?: number[];
}

/dtos/product-response.dto.ts:

export class ProductResponseDto {
  id: number;
  name: string;
  description: string;
  price: number;
  categories: CategoryResponseDto[];
}

export class CategoryResponseDto {
  id: number;
  name: string;
}

/products.mapper.ts:

import { Injectable } from '@nestjs/common';
import { Product } from '@src/database/entities/product';

import { ProductResponseDto } from './dtos/product-response.dto';

@Injectable()
export class ProductMapper {
  mapEntityToDto(product: Product): ProductResponseDto {
    return {
      id: product.id,
      name: product.name,
      description: product.description,
      price: product.price,
      categories:
        product.categories?.map((category) => ({
          id: category.id,
          name: category.name,
        })) || [],
    };
  }
}

/products.service.ts:

import {
  BadRequestException,
  HttpException,
  Injectable,
  InternalServerErrorException,
  Logger,
  NotFoundException,
} from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';

import { In, Repository } from 'typeorm';

import { Product } from '@src/database/entities/product';
import { CreateProductDto } from './dtos/create-product.dto';
import { UpdateProductDto } from './dtos/update-product.dto';
import { Category } from '@src/database/entities/category';
import { ProductMapper } from './products.mapper';

@Injectable()
export class ProductsService {
  private readonly logger = new Logger('ProductsService');

  constructor(
    @InjectRepository(Product, 'postgres')
    private readonly productRepository: Repository<Product>,
    @InjectRepository(Category, 'postgres')
    private readonly categoryRepository: Repository<Category>,
    private readonly productMapper: ProductMapper,
  ) {}

  async getAll(pageNo: number = 0, pageSize: number = 10) {
    try {
      // Ensure pageNo is a non-negative integer and pageSize is within reasonable limits
      if (pageNo < 0 || pageSize <= 0) {
        throw new BadRequestException('Invalid page number or page size');
      }

      // Calculate skip value based on page number and page size
      const skip = pageNo * pageSize;

      // Get products with pagination
      const [products, totalElements] =
        await this.productRepository.findAndCount({
          skip,
          take: pageSize,
          relations: ['categories'], // To load related categories for each product
        });

      // Calculate totalPages and whether it's the last page
      const totalPages = Math.ceil(totalElements / pageSize);
      const last = pageNo + 1 >= totalPages;

      // Map the result into the desired format
      return {
        content: products.map((product) =>
          this.productMapper.mapEntityToDto(product),
        ),
        pageNo,
        pageSize,
        totalElements,
        totalPages,
        last,
      };
    } catch (error) {
      this.handleError(error, 'An error occurred while getting products');
    }
  }

  async getById(id: number) {
    try {
      const product = await this.productRepository.findOne({
        where: { id },
        relations: ['categories'],
      });

      if (!product) {
        throw new NotFoundException('Product not found');
      }

      return this.productMapper.mapEntityToDto(product);
    } catch (error) {
      this.handleError(error, 'An error occurred while fetching product');
    }
  }

  async create(createProductDto: CreateProductDto) {
    try {
      // Convert category IDs to actual Category entities
      const categories = await this.categoryRepository.findBy({
        id: In(createProductDto.categories),
      });

      if (!categories.length) {
        throw new BadRequestException('Invalid category IDs');
      }

      // Create a new product with the categories attached
      const newProduct = this.productRepository.create({
        ...createProductDto,
        categories,
      });

      await this.productRepository.save(newProduct);
      return this.productMapper.mapEntityToDto(newProduct);
    } catch (error) {
      this.handleError(error, 'An error occurred while creating product');
    }
  }

  async update(id: number, updateProductDto: UpdateProductDto) {
    try {
      const { categories, ...updateProductDtoWithoutCategories } =
        updateProductDto;
      // Find the product by ID and preload with the updated values
      const product = await this.productRepository.preload({
        id,
        ...updateProductDtoWithoutCategories,
      });

      if (!product) {
        throw new NotFoundException('Product not found');
      }

      // If the update involves categories, convert category IDs to actual Category entities
      if (updateProductDto.categories) {
        const categories = await this.categoryRepository.findBy({
          id: In(updateProductDto.categories),
        });

        if (!categories.length) {
          throw new BadRequestException('Invalid category IDs');
        }

        product.categories = categories;
      }

      await this.productRepository.save(product);
      return this.productMapper.mapEntityToDto(product);
    } catch (error) {
      this.handleError(error, 'An error occurred while updating product');
    }
  }

  async delete(id: number) {
    try {
      const product = await this.productRepository.findOne({ where: { id } });

      if (!product) {
        throw new NotFoundException('Product not found');
      }

      await this.productRepository.remove(product);
      return { message: 'Product deleted successfully' };
    } catch (error) {
      this.handleError(error, 'An error occurred while deleting product');
    }
  }

  private handleError(error: unknown, defaultErrorMessage?: string) {
    // Log the error
    this.logger.error(error);

    // Handle known HTTP exceptions
    if (error instanceof HttpException) {
      throw error; // Preserve the original exception, don't modify it
    }

    // Handle unexpected errors
    if (error instanceof Error) {
      // Handle generic errors
      throw new InternalServerErrorException({
        message: defaultErrorMessage ?? 'An unexpected error occurred',
      });
    }

    // Default to a generic BadRequestException if error is unknown
    throw new BadRequestException({
      message: defaultErrorMessage ?? 'An error occurred in ProductsService',
    });
  }
}

/products.controller.ts:

import {
  Body,
  Controller,
  Delete,
  Get,
  Param,
  ParseIntPipe,
  Post,
  Put,
  Query,
} from '@nestjs/common';

import { ProductsService } from './products.service';
import { CreateProductDto } from './dtos/create-product.dto';
import { UpdateProductDto } from './dtos/update-product.dto';

@Controller('api/products')
export class ProductsController {
  constructor(private readonly productsService: ProductsService) {}

  @Get('/')
  getAll(
    @Query('pageNo', new ParseIntPipe({ errorHttpStatusCode: 400 }))
    pageNo: number = 0,
    @Query('pageSize', new ParseIntPipe({ errorHttpStatusCode: 400 }))
    pageSize: number = 10,
  ) {
    return this.productsService.getAll(pageNo, pageSize);
  }

  @Get('/:id')
  getById(@Param('id', ParseIntPipe) id: number) {
    return this.productsService.getById(id);
  }

  @Post('/')
  create(@Body() createProductDto: CreateProductDto) {
    return this.productsService.create(createProductDto);
  }

  @Put('/:id')
  update(
    @Param('id', ParseIntPipe) id: number,
    @Body() updateProductDto: UpdateProductDto,
  ) {
    return this.productsService.update(id, updateProductDto);
  }

  @Delete('/:id')
  delete(@Param('id', ParseIntPipe) id: number) {
    return this.productsService.delete(id);
  }
}

/products.module.ts:

import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { Category } from '@src/database/entities/category';
import { Product } from '@src/database/entities/product';
import { ProductsController } from './products.controller';
import { ProductsService } from './products.service';
import { ProductMapper } from './products.mapper';

@Module({
  imports: [TypeOrmModule.forFeature([Product, Category], 'postgres')],
  controllers: [ProductsController],
  providers: [ProductsService, ProductMapper],
  exports: [ProductsService],
})
export class ProductsModule {}

Test the endpoints

Create the following files inside the folder /rest-client/ and paste the content:

/products.http:

@base_url=http://localhost:3000/api/products

### Get All Products
GET {{base_url}}?pageNo=0&pageSize=10

### Get Product by ID
GET {{base_url}}/1

### Create a New Product
POST {{base_url}}
Content-Type: application/json

{
  "name": "Smartphone X",
  "description": "A high-end smartphone with an excellent camera.",
  "price": 999.99,
  "categories": [1, 2]
}

### Update Product
PUT {{base_url}}/1
Content-Type: application/json

{
  "name": "Smartphone Y",
  "description": "An updated version of Smartphone X.",
  "price": 899.99,
  "categories": [2]
}

### Delete Product
DELETE {{base_url}}/1

/categories.http:

@base_url = http://localhost:3000/api/categories

### Get All Categories
GET {{base_url}}?pageNo=0&pageSize=10

### Get Category by ID
GET {{base_url}}/1

### Create a New Category
POST {{base_url}}
Content-Type: application/json

{
  "name": "Electronics"
}

### Update Category
PUT {{base_url}}/1
Content-Type: application/json

{
  "name": "Updated Electronics"
}

### Delete Category
DELETE {{base_url}}/1

Now run the project with the following command:

npm run start

Conclusion

That's it. Now, we have a basic REST API working in NestJS. You can download the source code on my GitHub.

Any ideas for a tutorial or suggestions to improve this project? Feel free to share them in the comments!

Thank you for reading.

Spring Boot App as Windows Service

Javier Vega — Fri, 08 Sep 2023 07:35:24 +0000

In this tutorial, I will show you how to run a Spring Boot app as a Windows Service. For this purpose, I will use the app developed in Basic REST API with Spring Boot 2023.

First, you need to add some properties in the build section of the pom.xml file. This will allow us to generate the jar file.

<build>
    <!-- Name of the jar file -->
    <finalName>HotelRestAPI</finalName>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <executable>true</executable>
                <excludes>
                    <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                    </exclude>
                </excludes>
            </configuration>
        </plugin>
    </plugins>
</build>

Now, all you need to do is follow the next steps:

Create a folder for the service. I will use C:\HotelRestAPI - Service.
Generate the jar file using ./mvnw clean install from the Spring Boot App root directory. The jar file is generated inside the target directory of the project.
Copy the jar file to C:\HotelRestAPI - Service.
Download WinWS and sample-minimal.xml. (I am going to use WinSW-x64.exe).
Copy the WinSW-x64.exe and sample-minimal.xml files to C:\HotelRestAPI - Service.
Rename sample-minimal.xml to WinSW-x64.xml. You can name the .xml file whatever you want, but the .exe file and .xml file must have the same name.
Paste the following content in WinSW-x64.xml:

<service>
  <!-- ID of the service. 
  It should be unique across the Windows system-->
  <id>hotelrestapi</id>
  <!-- Display name of the service -->
  <name>Hotel REST API</name>
  <!-- Service description -->
  <description>
     This service is the backend for the hotel web page
  </description>
  <!-- Path to the executable, which should be started -->
  <executable>java</executable>
  <arguments>-jar HotelRestAPI.jar</arguments>
</service>

Then, open a terminal as an administrator from C:\HotelRestAPI - Service and run WinSW-x64.exe install.

Now, go open the Services Panel and look up your service. Then, right-click your service and click Start.

Once the service is up and running some files will be generated in C:\HotelRestAPI - Service.

Finally, you can check the service is working properly by making a request to http://localhost:8080/api/guests.

If you need to uninstall the service, you can run WinSW-x64.exe uninstall

That's it. Now, you can run your Spring Boot apps as Windows Services. You can see all the source code used in this tutorial on my GitHub.

Thank you for reading.

Basic REST API with Spring Boot 2023

Javier Vega — Thu, 07 Sep 2023 10:18:48 +0000

In this tutorial I will show you how to develop a very basic REST API using Spring Boot with Java and Maven.

Setup project

First, you need to create a Spring Boot project. To do it you can use Spring Initializr.

Add the following dependencies:

Lombok
Spring Web
Spring Data JPA
PostgreSQL Driver

Then, click generate to download a zip with the project.

Unzip the project and open it with an IDE of your preference, I am going to use IntelliJ IDEA Community Edition 2022.1.2.

Run the ApiApplication.java file:

Requirements review

Now, suppose you are given the following database design:

And you are required to create a REST API with the following endpoints for each entity:

Guest:

Method	Endpoint
GET	/api/guests
GET	/api/guests/{id}
POST	/api/guests
PUT	/api/guests/{id}
DELETE	/api/guests/{id}

Room:

Method	Endpoint
GET	/api/rooms
GET	/api/rooms/{id}
POST	/api/rooms
PUT	/api/rooms/{id}
DELETE	/api/rooms/{id}

Reservation:

Method	Endpoint
GET	/api/reservations
GET	/api/reservations/{id}
POST	/api/reservations
PUT	/api/reservations/{id}
DELETE	/api/reservations/{id}

Example of responses:
GET /api/guests

{
  "content": [
    {
      "id": 4,
      "name": "Javier",
      "lastName": "Vega",
      "email": "test@gmail.com"
    }
  ],
  "pageNo": 0,
  "pageSize": 10,
  "totalElements": 1,
  "totalPages": 1,
  "last": true
}

GET /api/guests/{id}

{
  "id": 4,
  "name": "Javier",
  "lastName": "Vega",
  "email": "test@gmail.com"
}

POST /api/guests

// Body
{
    "name": "Javier",
    "lastName": "Vega",
    "email": "test@gmail.com",
    "password": "1234"
}
// Response
{
    "id": 5,
    "name": "Javier",
    "lastName": "Vega",
    "email": "test@gmail.com"
}

PUT /api/guests/{id}

// Body
{
    "name": "Javier A.",
    "lastName": "Vega",
    "email": "test@gmail.com",
    "password": "1234"
}
// Response
{
    "id": 5,
    "name": "Javier A.",
    "lastName": "Vega",
    "email": "test@gmail.com"
}

DELETE /api/guests/{id}

Guest deleted

The database must be implemented using PostgreSQL.

Start coding

Project directory structure

Create the following packages inside com.hotel.api:

controller
dto
exception
mapper
model
repository
service

Project configuration

We need to use a PostgreSQL database so I have created one in my local machine. To connect our Spring Boot app to the database we need to add the following properties to the application.properties file:

spring.datasource.url=jdbc:postgresql://localhost:5432/hotel
spring.datasource.username=postgres
spring.datasource.password=1234
spring.datasource.driver-class-name=org.postgresql.Driver

# Testing
# This will drop any table in the database
# and create new ones base on the models
spring.jpa.hibernate.ddl-auto=create-drop

# Development
# This will update table schemas base on the models,
# but not will not remove columns that no longer exist
# in the models, it will just add new columns if needed.
#spring.jpa.hibernate.ddl-auto=update

# Production
#spring.jpa.hibernate.ddl-auto=none

# Show generated queries in logs - Spring Boot uses logback
logging.level.org.hibernate.SQL=DEBUG
logging.level.org.hibernate.type.descriptor.sql.BasicBinder=TRACE

Models

To create a model representing a table in our database we need to use the annotation @Entity. By default, the name of the table will be the class name in lowercase. If you want a custom name for your table use @Table(name = "your_table_name")

Each attribute of the class will correspond to a column in the table. By default, the column names will be the same as the attributes. If you want the column to have a different name from the attribute name use @Column(name = "your_column_name").

To make an attribute correspond to the PK of the table we need to use @Id. If you want the value to be auto-generated use @GeneratedValue(strategy = GenerationType.IDENTITY).

Since a guest can have many reservations, we need to use the annotation @OneToMany(mappedBy = "guest", cascade = CascadeType.ALL, orphanRemoval = true). This will make it possible to fetch the guest along with all their reservations in the future.

package com.hotel.api.model;

@Data // Add getters and setters for all attributes
@AllArgsConstructor
@NoArgsConstructor
@Entity
public class Guest {
    @Id // Make the attribute the PK of the table.
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private int id;
    private String name;
    @Column(name = "last_name")
    private String lastName;
    private String email;
    private String password;

    @OneToMany(mappedBy = "guest",
               cascade = CascadeType.ALL,
               orphanRemoval = true)
    private List<Reservation> reservations = new ArrayList<>();
}

package com.hotel.api.model;

@Data
@AllArgsConstructor
@NoArgsConstructor
@Entity
public class Room {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private int id;
    @Column(unique = true)
    private String number;
    private String type;
}

The reservation entity is associated with a room and a guest. If you want to query the data of these entities along with the Reservation data, you need to use @ManyToOne(fetch = FetchType.LAZY) and @JoinColumn(name = "FK_column_name").

package com.hotel.api.model;

@Data
@AllArgsConstructor
@NoArgsConstructor
@Entity
public class Reservation {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private int id;
    private String title;
    @Column(name = "date_start")
    private LocalDate dateStart;
    @Column(name = "date_end")
    private LocalDate dateEnd;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "room_id")
    private Room room;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "guest_id")
    private Guest guest;
}

Repositories

To create a Repository we only need to create an interface that extends JpaRepository<Entity, IdDataType>. This interface will provide us with some methods for querying the database like:

findAll()
findById()
save()
delete()

package com.hotel.api.repository;

public interface GuestRepository extends JpaRepository<Guest, Integer>
{
}

Service Interfaces

Now, we need to create an interface with the definition of all the methods that we wish to implement in our service.

package com.hotel.api.service;

public interface GuestService {
    GuestDto createGuest(Guest guest);
    GuestsResponse getAllGuests(int pageNo, int pageSize);
    GuestDto getGuestById(int id);
    GuestDto updateGuest(GuestDto guestDto, int id);
    void deleteGuestById(int id);

    GuestReservationsResponse getGuestReservations(int id);
}

Services Implementation

Services are classes with the implementation to query the data. To make a class a service you need to use the annotation @Service. Then, implements the interface of the service and overrides all its methods.

package com.hotel.api.service.impl;

@Service
public class GuestServiceImpl implements GuestService {

    private final GuestRepository guestRepository;

    @Autowired
    public GuestServiceImpl(GuestRepository guestRepository) {
        this.guestRepository = guestRepository;
    }

    @Override
    public GuestDto createGuest(Guest guest) {
        Guest newGuest = guestRepository.save(guest);
        return GuestMapper.mapToDto(newGuest);
    }

    @Override
    public GuestsResponse getAllGuests(int pageNo, int pageSize) {
        Pageable pageable = PageRequest.of(pageNo, pageSize);
        Page<Guest> guests = guestRepository.findAll(pageable);
        List<Guest> listOfGuests = guests.getContent();
        List<GuestDto> content = listOfGuests.stream()
        .map(GuestMapper::mapToDto)
        .collect(Collectors.toList());

        GuestsResponse guestsResponse = new GuestsResponse();
        guestsResponse.setContent(content);
        guestsResponse.setPageNo(guests.getNumber());
        guestsResponse.setPageSize(guests.getSize());
        guestsResponse.setTotalElements(guests.getTotalElements());
        guestsResponse.setTotalPages(guests.getTotalPages());
        guestsResponse.setLast(guests.isLast());

        return guestsResponse;
    }

    @Override
    public GuestDto getGuestById(int id) {
        Guest guest = guestRepository.findById(id)
        .orElseThrow(
            () -> new GuestNotFoundException("Guest could not be found")
        );
        return GuestMapper.mapToDto(guest);
    }

    @Override
    public GuestDto updateGuest(GuestDto guestDto, int id) {
        Guest guest = guestRepository.findById(id)
        .orElseThrow(
            () -> new GuestNotFoundException("Guest could not be found")
        );

        guest.setName(guestDto.getName());
        guest.setLastName(guestDto.getLastName());
        guest.setEmail(guestDto.getEmail());

        Guest updatedGuest = guestRepository.save(guest);

        return GuestMapper.mapToDto(updatedGuest);
    }

    @Override
    public void deleteGuestById(int id) {
        Guest guest = guestRepository.findById(id)
        .orElseThrow(
            () -> new GuestNotFoundException("Guest could not be found")
        );
        guestRepository.delete(guest);
    }

    @Override
    public GuestReservationsResponse getGuestReservations(int id) {
        Guest guest = guestRepository.findById(id)
        .orElseThrow(
            () -> new GuestNotFoundException("Guest could not be found")
        );
        return GuestMapper.mapToGuestReservationsResponse(guest);
    }
}

Controllers

Controllers are the last layer in the Spring Boot app, here is where you define the endpoints available in your REST API. To create a controller you need a class with the annotations @RestController and @RequestMapping("/api/"). What you put inside @RequestMapping will be added to all the mappings inside your controller.

For example, I have a method getGuests with the annotation @GetMapping("guests") so the endpoint that will call this method will be /api/guests.

All the methods mapped to an endpoint should return a ResponseEntity object. It will contain our data along with other properties like the status code.

package com.hotel.api.controller;

@RestController
@RequestMapping("/api/")
public class GuestController {
    private final GuestService guestService;

    @Autowired
    public GuestController(GuestService guestService) {
        this.guestService = guestService;
    }

    @GetMapping("guests")
    public ResponseEntity<GuestsResponse> getGuests(
            @RequestParam(
                value = "pageNo",
                defaultValue = "0",
                required = false) int pageNo,
            @RequestParam(
                value = "pageSize",
                defaultValue = "10",
                required = false) int pageSize
    ){
        return new ResponseEntity<>(
            guestService.getAllGuests(pageNo, pageSize), HttpStatus.OK
        );
    }

    @GetMapping("guests/{id}")
    public ResponseEntity<GuestDto> guestDetail(
        @PathVariable int id){
        return new ResponseEntity<>(
            guestService.getGuestById(id), HttpStatus.OK
        );
    }

    @PostMapping("guests")
    @ResponseStatus(HttpStatus.CREATED)
    public ResponseEntity<GuestDto> createGuest(
        @RequestBody Guest guest){
        return new ResponseEntity<>(
            guestService.createGuest(guest), HttpStatus.CREATED);
    }

    @PutMapping("guests/{id}")
    public ResponseEntity<GuestDto> updateGuest(
        @RequestBody GuestDto guestDto,
        @PathVariable("id") int guestId
    ){
        GuestDto response = guestService.updateGuest(guestDto, guestId);
        return new ResponseEntity<>(response, HttpStatus.OK);
    }

    @DeleteMapping("guests/{id}")
    public ResponseEntity<String> deleteGuest(
        @PathVariable("id") int guestId
    ){
        guestService.deleteGuestById(guestId);
        return new ResponseEntity<>("Guest deleted", HttpStatus.OK);
    }

    @GetMapping("guests/{id}/reservations")
    public ResponseEntity<GuestReservationsResponse> guestReservations(
        @PathVariable int id
    ){
        return new ResponseEntity<>(
            guestService.getGuestReservations(id), HttpStatus.OK
        );
    }
}

DTOs (Data Transfer Objects)

Throughout the code, you should see that I used a class guestDto. DTO classes are intended to be an intermediary between the entities and the data that is sent to the client.

For example, the Guest model has an attribute password. When we query the data from the database it will bring all the attributes by default, but I don't want to send them all to the client. So, I need a class that contains only the necessary attributes. This is when DTO classes come into play.

package com.hotel.api.dto;

@Data
public class GuestDto {
    private int id;
    private String name;
    private String lastName;
    private String email;
}

I also used another DTO called GuestReservationsResponse to send the guest data along with all their reservations.

package com.hotel.api.dto;

@Data
public class GuestReservationsResponse{
    private int id;
    private String name;
    private String lastName;
    private String email;
    private List<ReservationInfo> reservations;
}

Finally, I used another DTO called GuestsResponse to send the guests using pagination.

package com.hotel.api.dto;

@Data
public class GuestsResponse {
    private List<GuestDto> content;
    private int pageNo;
    private int pageSize;
    private long totalElements;
    private int totalPages;
    private boolean last;
}

Mappers

To make conversions between entities and DTOs I used mappers which are classes that have methods to convert entity models to DTOs and vice versa.

In this case, I created a class GuestMapper with the methods mapToDto and mapToGuestReservationsResponse since I need to do those conversions frequently.

package com.hotel.api.mapper;

@NoArgsConstructor
public class GuestMapper {
    public static GuestDto mapToDto(Guest guest){
        GuestDto guestDto = new GuestDto();
        guestDto.setId(guest.getId());
        guestDto.setName(guest.getName());
        guestDto.setLastName(guest.getLastName());
        guestDto.setEmail(guest.getEmail());
        return guestDto;
    }

    public static GuestReservationsResponse mapToGuestReservationsResponse(Guest guest){
        GuestReservationsResponse guestReservationsResponse = new GuestReservationsResponse();

        List<ReservationInfo> reservationsInfo = ReservationMapper.mapElementsToReservationInfo(
            guest.getReservations()
        );

        guestReservationsResponse.setId(guest.getId());
        guestReservationsResponse.setName(guest.getName());
        guestReservationsResponse.setLastName(
            guest.getLastName()
        );
        guestReservationsResponse.setEmail(guest.getEmail());
        guestReservationsResponse.setReservations(reservationsInfo);

        return guestReservationsResponse;
    }
}

Error Handling

Throughout the code, you should see that I used a class GuestNotFoundException. This class will be thrown as an exception and will be handled by Spring Boot which will send an error response to the client.

package com.hotel.api.exception;

public class GuestNotFoundException extends RuntimeException{
    @Serial
    private static final long serialVersionUID = 1;

    public GuestNotFoundException(String message){
        super(message);
    }
}

To add error handling to our Spring Boot app we need to create a class with the annotation @ControllerAdvice and inside this class, we need to create a method that will handle an exception and send an error response to the client.

The method we define needs to be annotated with @ExceptionHandler(ExceptionClass.class) the ExceptionClass should be a class that extends Exception. Also, our class needs to return a ResponseEntity<ErrorObject> where ErrorObject can be any class we want it to be.

In this specific case ExceptionClass is GuestNotFoundException and ErrorObject is ErrorObject.

package com.hotel.api.exception;

@ControllerAdvice
public class GlobalException {
    @ExceptionHandler(GuestNotFoundException.class)
    public ResponseEntity<ErrorObject> handleGuestNotFoundException(
        GuestNotFoundException ex, WebRequest request
    ){
        ErrorObject errorObject = new ErrorObject();

        errorObject.setStatusCode(HttpStatus.NOT_FOUND.value());
        errorObject.setMessage(ex.getMessage());
        errorObject.setTimestamp(new Date());

        return new ResponseEntity<ErrorObject>(
            errorObject, HttpStatus.NOT_FOUND
        );
    }
}

package com.hotel.api.exception;

@Data
public class ErrorObject {
    private Integer statusCode;
    private String message;
    private Date timestamp;
}

Conclusion

That's it. Now, we have a basic REST API working in Spring Boot. I have explained the basics of building REST APIs with Spring Boot. The code for the room and reservation repositories, services, and controllers are almost the same as the guest. You can see all the source code on my GitHub.

Thank you for reading.