Java Notes

REST API with Spring Boot

Building RESTful APIs with Spring Boot - REST principles, controller annotations, request/response handling, pagination, HATEOAS, and API versioning.

REST Principles

REST (Representational State Transfer) is an architectural style for designing networked applications:

Principle	Description
Stateless	Each request contains all info needed
Client-Server	Separation of concerns
Uniform Interface	Standard HTTP methods (GET, POST, PUT, DELETE)
Resource-Based	URLs represent resources, not actions
Layered System	Client doesn't know if connected directly to server

REST URL Design

GET /api/users	Get all users
GET /api/users/1	Get user with id 1
POST /api/users	Create new user
PUT /api/users/1	Update user 1
DELETE /api/users/1	Delete user 1
GET /api/users/1/orders	Get orders of user 1
GET /api/users?page=1&size=10	Paginated users

Request and Response Handling

Path Variables

java example

@GetMapping("/users/{userId}/orders/{orderId}")
public Order getOrder(
        @PathVariable Long userId,
        @PathVariable Long orderId) {
    return orderService.findByUserAndId(userId, orderId);
}

Request Parameters

java example

@GetMapping("/products")
public Page<Product> getProducts(
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "10") int size,
        @RequestParam(defaultValue = "id") String sortBy,
        @RequestParam(defaultValue = "asc") String direction,
        @RequestParam(required = false) String category) {
    
    Sort sort = direction.equalsIgnoreCase("desc") 
        ? Sort.by(sortBy).descending() 
        : Sort.by(sortBy).ascending();
    
    Pageable pageable = PageRequest.of(page, size, sort);
    
    if (category != null) {
        return productService.findByCategory(category, pageable);
    }
    return productService.findAll(pageable);
}

Request Body

java example

@PostMapping("/users")
public ResponseEntity<UserResponse> createUser(@RequestBody @Valid UserRequest request) {
    User user = userService.create(request);
    UserResponse response = mapToResponse(user);
    
    URI location = ServletUriComponentsBuilder
            .fromCurrentRequest()
            .path("/{id}")
            .buildAndExpand(user.getId())
            .toUri();
    
    return ResponseEntity.created(location).body(response);
}

Request Headers

java example

@GetMapping("/profile")
public UserProfile getProfile(
        @RequestHeader("Authorization") String authHeader,
        @RequestHeader(value = "Accept-Language", defaultValue = "en") String language) {
    String token = authHeader.replace("Bearer ", "");
    return userService.getProfile(token, language);
}

ResponseEntity for Full Control

java example

@RestController
@RequestMapping("/api/products")
public class ProductController {

    @GetMapping("/{id}")
    public ResponseEntity<Product> getProduct(@PathVariable Long id) {
        return productService.findById(id)
                .map(ResponseEntity::ok)
                .orElse(ResponseEntity.notFound().build());
    }

    @PostMapping
    public ResponseEntity<Product> createProduct(@RequestBody @Valid ProductRequest request) {
        Product product = productService.create(request);
        return ResponseEntity
                .status(HttpStatus.CREATED)
                .header("X-Product-Id", product.getId().toString())
                .body(product);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteProduct(@PathVariable Long id) {
        productService.delete(id);
        return ResponseEntity.noContent().build();
    }
}

DTO Pattern (Data Transfer Objects)

java example

// Request DTO
@Data
public class CreateUserRequest {
    @NotBlank(message = "Name is required")
    private String name;
    
    @Email(message = "Invalid email")
    @NotBlank
    private String email;
    
    @Min(18) @Max(120)
    private int age;
    
    @NotBlank
    @Size(min = 8, message = "Password must be at least 8 characters")
    private String password;
}

// Response DTO (no password!)
@Data
@Builder
public class UserResponse {
    private Long id;
    private String name;
    private String email;
    private int age;
    private LocalDateTime createdAt;
}

// Mapper
@Component
public class UserMapper {
    public User toEntity(CreateUserRequest request) {
        User user = new User();
        user.setName(request.getName());
        user.setEmail(request.getEmail());
        user.setAge(request.getAge());
        return user;
    }
    
    public UserResponse toResponse(User user) {
        return UserResponse.builder()
                .id(user.getId())
                .name(user.getName())
                .email(user.getEmail())
                .age(user.getAge())
                .createdAt(user.getCreatedAt())
                .build();
    }
}

Pagination

java example

@GetMapping
public ResponseEntity<Map<String, Object>> getAllUsers(
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "10") int size) {
    
    Page<User> userPage = userService.findAll(PageRequest.of(page, size));
    
    Map<String, Object> response = new HashMap<>();
    response.put("users", userPage.getContent());
    response.put("currentPage", userPage.getNumber());
    response.put("totalItems", userPage.getTotalElements());
    response.put("totalPages", userPage.getTotalPages());
    response.put("hasNext", userPage.hasNext());
    response.put("hasPrevious", userPage.hasPrevious());
    
    return ResponseEntity.ok(response);
}

API Versioning Strategies

java example

// 1. URL Versioning (Most Common)
@RestController
@RequestMapping("/api/v1/users")
public class UserControllerV1 { }

@RestController
@RequestMapping("/api/v2/users")
public class UserControllerV2 { }

// 2. Header Versioning
@GetMapping(value = "/users", headers = "X-API-VERSION=1")
public List<UserV1> getUsersV1() { }

@GetMapping(value = "/users", headers = "X-API-VERSION=2")
public List<UserV2> getUsersV2() { }

// 3. Content Negotiation
@GetMapping(value = "/users", produces = "application/vnd.company.v1+json")
public List<UserV1> getUsersV1() { }

CORS Configuration

java example

@Configuration
public class WebConfig implements WebMvcConfigurer {
    
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
                .allowedOrigins("http://localhost:3000", "https://myapp.com")
                .allowedMethods("GET", "POST", "PUT", "DELETE")
                .allowedHeaders("*")
                .allowCredentials(true)
                .maxAge(3600);
    }
}

Interview Key Points

@RestController = @Controller + @ResponseBody on every method
Use ResponseEntity for full control over status codes and headers
DTOs separate internal model from API contract
@PathVariable for URL segments; @RequestParam for query params
Always use @Valid with request DTOs for input validation
Use pagination for large datasets (never return all records)
Version APIs via URL path (/api/v1/, /api/v2/)
CORS must be configured for frontend-backend separation

Summary

In this chapter, we learned about REST API with Spring Boot in detail. Here are the key points:

Basic introduction to the concept and why it is needed
Syntax and structure with complete examples
Internal working and best practices
Real-world applications and use cases
Common mistakes and how to avoid them
How this topic is asked in interviews

To practice these concepts, write and run the code in your IDE and verify the output. Modify each example and experiment so that you deeply understand the concept.

Continue the lesson path

Study next in this module

4 connected lessons

01Spring FrameworkSpring Boot IntroductionComplete introduction to Spring Boot - auto-configuration, starter dependencies, embedded servers, creating your first Spring Boot application, and project structure.02Spring FrameworkValidation in Spring BootComplete guide to input validation in Spring Boot - Jakarta Bean Validation, custom validators, group validation, and validation error handling.03Spring FrameworkCRUD ApplicationBuild a complete CRUD application with Spring Boot - project setup, layered architecture, full CRUD operations, testing, and deployment.04Spring FrameworkSpring Data JPAComplete guide to Spring Data JPA - entity mapping, repository interfaces, query methods, JPQL, native queries, relationships, and database operations.

PreviousSpring Boot Introduction NextValidation in Spring Boot

Java Notes

REST API with Spring Boot

Building RESTful APIs with Spring Boot - REST principles, controller annotations, request/response handling, pagination, HATEOAS, and API versioning.

REST Principles

REST (Representational State Transfer) is an architectural style for designing networked applications:

Principle	Description
Stateless	Each request contains all info needed
Client-Server	Separation of concerns
Uniform Interface	Standard HTTP methods (GET, POST, PUT, DELETE)
Resource-Based	URLs represent resources, not actions
Layered System	Client doesn't know if connected directly to server

REST URL Design

GET /api/users	Get all users
GET /api/users/1	Get user with id 1
POST /api/users	Create new user
PUT /api/users/1	Update user 1
DELETE /api/users/1	Delete user 1
GET /api/users/1/orders	Get orders of user 1
GET /api/users?page=1&size=10	Paginated users

Request and Response Handling

Path Variables

java example

@GetMapping("/users/{userId}/orders/{orderId}")
public Order getOrder(
        @PathVariable Long userId,
        @PathVariable Long orderId) {
    return orderService.findByUserAndId(userId, orderId);
}

Request Parameters

java example

@GetMapping("/products")
public Page<Product> getProducts(
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "10") int size,
        @RequestParam(defaultValue = "id") String sortBy,
        @RequestParam(defaultValue = "asc") String direction,
        @RequestParam(required = false) String category) {
    
    Sort sort = direction.equalsIgnoreCase("desc") 
        ? Sort.by(sortBy).descending() 
        : Sort.by(sortBy).ascending();
    
    Pageable pageable = PageRequest.of(page, size, sort);
    
    if (category != null) {
        return productService.findByCategory(category, pageable);
    }
    return productService.findAll(pageable);
}

Request Body

java example

@PostMapping("/users")
public ResponseEntity<UserResponse> createUser(@RequestBody @Valid UserRequest request) {
    User user = userService.create(request);
    UserResponse response = mapToResponse(user);
    
    URI location = ServletUriComponentsBuilder
            .fromCurrentRequest()
            .path("/{id}")
            .buildAndExpand(user.getId())
            .toUri();
    
    return ResponseEntity.created(location).body(response);
}

Request Headers

java example

@GetMapping("/profile")
public UserProfile getProfile(
        @RequestHeader("Authorization") String authHeader,
        @RequestHeader(value = "Accept-Language", defaultValue = "en") String language) {
    String token = authHeader.replace("Bearer ", "");
    return userService.getProfile(token, language);
}

ResponseEntity for Full Control

java example

@RestController
@RequestMapping("/api/products")
public class ProductController {

    @GetMapping("/{id}")
    public ResponseEntity<Product> getProduct(@PathVariable Long id) {
        return productService.findById(id)
                .map(ResponseEntity::ok)
                .orElse(ResponseEntity.notFound().build());
    }

    @PostMapping
    public ResponseEntity<Product> createProduct(@RequestBody @Valid ProductRequest request) {
        Product product = productService.create(request);
        return ResponseEntity
                .status(HttpStatus.CREATED)
                .header("X-Product-Id", product.getId().toString())
                .body(product);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteProduct(@PathVariable Long id) {
        productService.delete(id);
        return ResponseEntity.noContent().build();
    }
}

DTO Pattern (Data Transfer Objects)

java example

// Request DTO
@Data
public class CreateUserRequest {
    @NotBlank(message = "Name is required")
    private String name;
    
    @Email(message = "Invalid email")
    @NotBlank
    private String email;
    
    @Min(18) @Max(120)
    private int age;
    
    @NotBlank
    @Size(min = 8, message = "Password must be at least 8 characters")
    private String password;
}

// Response DTO (no password!)
@Data
@Builder
public class UserResponse {
    private Long id;
    private String name;
    private String email;
    private int age;
    private LocalDateTime createdAt;
}

// Mapper
@Component
public class UserMapper {
    public User toEntity(CreateUserRequest request) {
        User user = new User();
        user.setName(request.getName());
        user.setEmail(request.getEmail());
        user.setAge(request.getAge());
        return user;
    }
    
    public UserResponse toResponse(User user) {
        return UserResponse.builder()
                .id(user.getId())
                .name(user.getName())
                .email(user.getEmail())
                .age(user.getAge())
                .createdAt(user.getCreatedAt())
                .build();
    }
}

Pagination

java example

@GetMapping
public ResponseEntity<Map<String, Object>> getAllUsers(
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "10") int size) {
    
    Page<User> userPage = userService.findAll(PageRequest.of(page, size));
    
    Map<String, Object> response = new HashMap<>();
    response.put("users", userPage.getContent());
    response.put("currentPage", userPage.getNumber());
    response.put("totalItems", userPage.getTotalElements());
    response.put("totalPages", userPage.getTotalPages());
    response.put("hasNext", userPage.hasNext());
    response.put("hasPrevious", userPage.hasPrevious());
    
    return ResponseEntity.ok(response);
}

API Versioning Strategies

java example

// 1. URL Versioning (Most Common)
@RestController
@RequestMapping("/api/v1/users")
public class UserControllerV1 { }

@RestController
@RequestMapping("/api/v2/users")
public class UserControllerV2 { }

// 2. Header Versioning
@GetMapping(value = "/users", headers = "X-API-VERSION=1")
public List<UserV1> getUsersV1() { }

@GetMapping(value = "/users", headers = "X-API-VERSION=2")
public List<UserV2> getUsersV2() { }

// 3. Content Negotiation
@GetMapping(value = "/users", produces = "application/vnd.company.v1+json")
public List<UserV1> getUsersV1() { }

CORS Configuration

java example

@Configuration
public class WebConfig implements WebMvcConfigurer {
    
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
                .allowedOrigins("http://localhost:3000", "https://myapp.com")
                .allowedMethods("GET", "POST", "PUT", "DELETE")
                .allowedHeaders("*")
                .allowCredentials(true)
                .maxAge(3600);
    }
}

Interview Key Points

@RestController = @Controller + @ResponseBody on every method
Use ResponseEntity for full control over status codes and headers
DTOs separate internal model from API contract
@PathVariable for URL segments; @RequestParam for query params
Always use @Valid with request DTOs for input validation
Use pagination for large datasets (never return all records)
Version APIs via URL path (/api/v1/, /api/v2/)
CORS must be configured for frontend-backend separation

Summary

In this chapter, we learned about REST API with Spring Boot in detail. Here are the key points:

Basic introduction to the concept and why it is needed
Syntax and structure with complete examples
Internal working and best practices
Real-world applications and use cases
Common mistakes and how to avoid them
How this topic is asked in interviews

To practice these concepts, write and run the code in your IDE and verify the output. Modify each example and experiment so that you deeply understand the concept.

Continue the lesson path

Study next in this module

4 connected lessons

PreviousSpring Boot Introduction NextValidation in Spring Boot