Spring Boot و REST APISpring Boot & REST APIs

Hi. Let's build and understand one of the most-used tools in the Java world from the ground up. Many people treat Spring Boot as "magic" — they write some code, run it, everything works, but they don't know why. The goal of this lesson is to turn that magic into a transparent, understandable machine for you. By the end, Spring Boot won't be a black box: you'll know what its engine does inside, and in an interview you'll be able to explain every piece of it with confidence.

Part 0 — a few words you must know

Before we start, let's anchor three terms with analogies so they never land on you cold later.

• bean: any object that Spring itself creates, holds, and hands to others. Picture a central storekeeper holding all your ready-made parts; each part is a bean and the storekeeper is the "Spring container."
• classpath: the list of all libraries (jars) and classes your program can reach at runtime. Like a workshop's tool shelf — whatever is on the shelf is available.
• annotation: a label you stick on a class or method to tell the framework "treat this a certain way." Like a "Fragile" label on a box that dictates how the courier handles it.

The mental model: what is Spring Boot really?

So be precise: Spring Boot is not a framework layered on top of Spring. It is an opinionated packaging of Spring Framework, plus a startup-time engine that inspects your classpath, your beans, and your properties, then wires up sensible defaults so you don't write boilerplate. "Opinionated" means Boot has an opinion about what is usually correct, and it makes that the default.

Two ideas do almost all of this work:

1. Convention over configuration, via conditions. Boot ships hundreds of @Configuration classes, each guarded by a @Conditional annotation. @Conditional means "only apply this when a certain condition holds." At startup, Boot evaluates those conditions against your application and only applies the ones that fit.

2. Backing off gracefully. Almost every auto-configuration carries @ConditionalOnMissingBean, meaning "only create this bean if the user hasn't." The moment you define a bean yourself, Boot steps aside. That's why Boot feels magical but never fights you — it always respects your explicit decision.

The Spring Boot 3 baseline (verify these before any migration)

These are version facts a senior should know cold:

• Java 17 minimum (Java 21+ recommended; virtual threads supported via spring.threads.virtual.enabled=true).
• Jakarta EE 9+ namespace: every javax.* import from the servlet/validation/persistence/JMS APIs becomes jakarta.*. This is the single biggest breaking change from Boot 2. "Namespace" here just means the package prefix; the whole industry migrated from javax to jakarta, and Boot 3 only understands the new form.
• Built on Spring Framework 6, Tomcat 10.1, Hibernate 6.
• First-class support for GraalVM native images (compiling to a fast-starting native executable instead of running on the JVM) and Micrometer Observation for tracing/metrics.

Here is the whole startup process as one mental diagram:

your app classpath + your beans + your properties
                 │
   ┌─────────────┴──────────────┐
   │  @EnableAutoConfiguration   │  (implied by @SpringBootApplication)
   └─────────────┬──────────────┘
                 ▼
  read AutoConfiguration.imports  ── list of candidate @AutoConfiguration classes
                 ▼
  evaluate @Conditional guards     ── keep the ones that fit
                 ▼
  register beans (backing off on your own beans)

Auto-configuration mechanics

Now let's go inside the engine.

The entry point

@SpringBootApplication // = @Configuration + @ComponentScan + @EnableAutoConfiguration
public class ShopApplication {
    public static void main(String[] args) {
        SpringApplication.run(ShopApplication.class, args);
    }
}

That familiar @SpringBootApplication is really three annotations in one coat: @Configuration (this class is a source of bean definitions), @ComponentScan (scan surrounding packages to find your beans), and @EnableAutoConfiguration (the magic engine).

@EnableAutoConfiguration imports a class called AutoConfigurationImportSelector. That selector reads a metadata file from every jar on the classpath. In other words, each library you put on the shelf carries a little instruction sheet that says "if I'm here, consider these beans."

spring.factories is dead — the mechanism is now AutoConfiguration.imports

In Boot 2.7 this mechanism moved, and in Boot 3 the old path is gone entirely. Auto-configuration candidates are now listed one-class-per-line in:

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

com.acme.audit.AuditAutoConfiguration
com.acme.ratelimit.RateLimitAutoConfiguration

The old EnableAutoConfiguration= key in META-INF/spring.factories is no longer read for auto-configuration. (spring.factories still exists for other extension points like ApplicationListener, but not for auto-config.) Why was this a good change? It cut startup cost — Boot no longer has to parse one big properties file and instantiate every listed class just to sort it; the dedicated file is cheaper to read, and ordering is carried by the annotations themselves.

The @AutoConfiguration annotation

If you want to write your own auto-config library (say, an internal starter for your company), you mark the class with @AutoConfiguration, not plain @Configuration:

@AutoConfiguration(after = DataSourceAutoConfiguration.class) // ordering hint
@ConditionalOnClass(RedisTemplate.class)                      // only if Redis is on the classpath
public class RateLimitAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean               // back off if the app already defines one
    @ConditionalOnProperty(prefix = "acme.ratelimit", name = "enabled",
                           havingValue = "true", matchIfMissing = true)
    RateLimiter rateLimiter(RateLimitProperties props) {
        return new TokenBucketRateLimiter(props.getCapacity(), props.getRefill());
    }
}

Read this like a sentence, clause by clause: "Run this configuration after DataSourceAutoConfiguration; only if the class RedisTemplate is on the classpath; create a RateLimiter, but only if the user hasn't defined one, and if a property named acme.ratelimit.enabled is on (and if it isn't set at all, default to on)." See how everything is conditional?

An important subtlety: @AutoConfiguration implies @Configuration(proxyBeanMethods = false). That means each @Bean method is a lightweight factory, not a proxy. A "proxy" here means Spring wraps an invisible shell around your class to intercept behavior. With proxyBeanMethods = false there is no shell: startup is faster, but you can no longer call one @Bean method from inside another and get the same cached singleton back — you get a fresh instance. On top of that, @AutoConfiguration carries the before/after/beforeName/afterName ordering attributes. Why does ordering matter? Because a later auto-config's @ConditionalOnMissingBean must be able to see the beans that earlier auto-configs created, or it will decide wrong.

The condition catalog

Treat this table as the toolbox of conditions; each says "when it fires":

Debugging what got configured

When you ask "why did this bean/endpoint not get created at all?", this technique saves you:

# Prints the "CONDITIONS EVALUATION REPORT": Positive matches, Negative matches, Exclusions
debug=true

Or hit the Actuator conditions endpoint (we'll cover it shortly).

Starters

More precisely: a starter is a dependency-only jar (a curated pom.xml with no code) that pulls a coherent set of libraries. For example, spring-boot-starter-web brings Spring MVC, Jackson, validation, and embedded Tomcat. Note the division of labor: the starter provides only the jars; the auto-config classes inside those jars provide the wiring. Version alignment comes from a BOM (a coordinated list of versions) named spring-boot-dependencies, imported by the parent POM — which is why you list starters without version numbers and the versions still line up.

Externalized configuration & profiles

A good software rule is that settings (like a port or a database password) should not be hard-coded, but come from outside so they can change without recompiling. This is called externalized configuration.

Boot resolves properties from this ordered PropertySource list (higher = stronger):

1. Devtools defaults
2. @TestPropertySource / test props
3. Command-line args        (--server.port=9000)
4. SPRING_APPLICATION_JSON
5. OS environment variables (SERVER_PORT=9000)  ← relaxed binding
6. Java system properties   (-Dserver.port=9000)
7. application-{profile}.yml / .properties
8. application.yml / .properties
9. @PropertySource
10. default properties

That term relaxed binding means Spring isn't strict about the property's name: server.port, SERVER_PORT, server_port, and serverPort all bind to the same property. Environment variables use the uppercased, underscore form (SERVER_PORT) — this is essential for containers, since the OS usually only accepts that form.

Type-safe configuration with @ConfigurationProperties

Instead of scattering @Value("${...}") all over the code, it's better to gather related settings into one class. This is called type-safe: each value has a defined, checked type. It's bound once, validated, and refactorable:

@ConfigurationProperties(prefix = "acme.ratelimit")
@Validated
public record RateLimitProperties(
        @Positive int capacity,
        @DurationUnit(ChronoUnit.SECONDS) Duration refill) {
    public RateLimitProperties {
        // records support compact-constructor defaults
        if (refill == null) refill = Duration.ofSeconds(1);
    }
}

Enable it with @EnableConfigurationProperties(RateLimitProperties.class) (which auto-configs do themselves) or @ConfigurationPropertiesScan. Using a record (Java's immutable data type) gives you immutable, constructor-bound config for free — the values can't change after construction, which prevents accidental bugs.

Profiles

A profile is a named set of settings for a particular environment — for instance dev (development) and prod (production). One file, several modes:

# application.yml
spring:
  config:
    activate:
      on-profile: prod        # Boot 2.4+ way (multi-document with ---)
server:
  port: 8080
---
spring:
  config:
    activate:
      on-profile: dev
logging:
  level:
    root: DEBUG

Activate with --spring.profiles.active=prod or SPRING_PROFILES_ACTIVE=prod. You can also put @Profile("prod") on beans so they're created only in that environment.

Building the REST layer

Now to the part the end user actually sees: the API itself.

Controller basics

A controller is a class that receives incoming HTTP requests and responds. Think of it as the front desk of an office: a visitor comes, hands over their request, and the desk returns the answer.

@RestController                 // = @Controller + @ResponseBody on every method
@RequestMapping("/api/orders")
public class OrderController {

    private final OrderService service;
    OrderController(OrderService service) { this.service = service; }

    @GetMapping("/{id}")
    public OrderDto get(@PathVariable long id) {
        return service.find(id);            // serialized to JSON by Jackson (HttpMessageConverter)
    }

    @GetMapping
    public Page<OrderDto> list(@RequestParam(defaultValue = "0") int page,
                               @RequestParam(defaultValue = "20") int size) {
        return service.list(PageRequest.of(page, size));
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public ResponseEntity<OrderDto> create(@Valid @RequestBody CreateOrderRequest req,
                                           UriComponentsBuilder uri) {
        OrderDto created = service.create(req);
        URI location = uri.path("/api/orders/{id}").build(created.id());
        return ResponseEntity.created(location).body(created); // 201 + Location header
    }
}

That @RestController equals @Controller + @ResponseBody on every method; it means "return each method's output directly as the response body (not an HTML page)." The term serialize means converting a Java object into a transferable format like JSON; the library that does this is Jackson, working through an HttpMessageConverter.

Notes a senior should internalize:

• Return the domain/DTO object directly and let the HttpMessageConverter (Jackson) serialize it. Reach for ResponseEntity only when you need to control status, headers, or body conditionally.
• The composed @RequestMapping variants (@GetMapping, @PostMapping, …) also carry produces/consumes for content negotiation and params/headers for finer routing, in addition to the path.
• Never expose entities. (An entity is a class mapped directly to a database table.)

Validation with Bean Validation

Validation means checking that input from the client is valid before you trust it. Boot 3 uses Jakarta Bean Validation (jakarta.validation.*), and its starter (spring-boot-starter-validation) pulls the Hibernate Validator library.

public record CreateOrderRequest(
        @NotBlank String customerEmail,
        @NotEmpty @Valid List<LineItem> items,     // @Valid cascades into each element
        @Positive BigDecimal total) {

    public record LineItem(@NotBlank String sku, @Min(1) int qty) {}
}

That @Valid on the list is called "cascading": it carries validation into each element of the list, not just the list itself. When you put @Valid on a @RequestBody parameter, validation fires before the method body runs; if it fails, a MethodArgumentNotValidException is thrown (which Boot maps to status 400).

But validating individual simple parameters like @RequestParam/@PathVariable works differently: you must mark the class with @Validated and put the constraints directly on the parameters. These throw a different exception, ConstraintViolationException:

@RestController
@Validated                                    // enables method-level param validation
public class SearchController {
    @GetMapping("/search")
    public List<Hit> search(@RequestParam @Size(min = 3) String q,
                            @RequestParam @Max(100) int limit) { ... }
}

Exception handling & RFC 9457 ProblemDetail

Spring Framework 6 implements RFC 9457 (formerly RFC 7807), "Problem Details for HTTP APIs." ProblemDetail is that standard error body:

{
  "type": "https://api.acme.com/problems/insufficient-stock",
  "title": "Insufficient stock",
  "status": 409,
  "detail": "SKU ABC-1 has 2 units, 5 requested",
  "instance": "/api/orders",
  "sku": "ABC-1"
}

Enable it globally with one property:

spring.mvc.problemdetails.enabled=true   # makes Spring MVC's built-in exceptions return ProblemDetail

Now centralize error handling in one place. @RestControllerAdvice is a central class that catches errors from all controllers at once. If you extend ResponseEntityExceptionHandler, you also get RFC-9457 responses for all the built-in Spring MVC exceptions (unsupported media type, unreadable body, validation, etc.):

@RestControllerAdvice
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {

    @ExceptionHandler(InsufficientStockException.class)
    ProblemDetail handleStock(InsufficientStockException ex) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT, ex.getMessage());
        pd.setType(URI.create("https://api.acme.com/problems/insufficient-stock"));
        pd.setTitle("Insufficient stock");
        pd.setProperty("sku", ex.getSku());        // extension member, rendered top-level via Jackson mixin
        return pd;
    }

    // Override to customize how bean-validation failures render as ProblemDetail
    @Override
    protected ResponseEntity<Object> handleMethodArgumentNotValid(
            MethodArgumentNotValidException ex, HttpHeaders headers,
            HttpStatusCode status, WebRequest request) {
        ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
        pd.setTitle("Validation failed");
        pd.setProperty("errors", ex.getBindingResult().getFieldErrors().stream()
                .collect(Collectors.toMap(FieldError::getField, FieldError::getDefaultMessage)));
        return ResponseEntity.badRequest().body(pd);
    }
}

That pd.setProperty("sku", ...) adds an "extension member": a custom field beyond the standard ones, which a Jackson mixin unwraps to the top level of the JSON (not nested).

You have a few other options too: the cleanest approach for your own exceptions is to implement ErrorResponse (or throw ErrorResponseException) so the exception carries its own HTTP mapping — no advice needed. @ControllerAdvice/@RestControllerAdvice can be scoped with basePackages, assignableTypes, or annotations when you have multiple advices. And @ResponseStatus on a custom exception is the low-ceremony option, but it can't set a body.

Content negotiation

Content negotiation means the client and server agreeing on the response format (JSON or XML or …). The client says "I understand these formats," and the server picks the best one it can.

Spring chooses the response format by consulting, in order: the path extension (disabled by default in Boot 3+), a format query param (opt-in, you must turn it on), and finally the Accept header. It then matches the requested media types against the controller's produces and the registered HttpMessageConverters, and picks the best converter.

@GetMapping(value = "/{id}", produces = {MediaType.APPLICATION_JSON_VALUE,
                                         MediaType.APPLICATION_XML_VALUE})
public OrderDto get(@PathVariable long id) { ... }  // Accept: application/xml → XML if Jackson-XML present

Accept: application/json → Jackson. Add jackson-dataformat-xml and XML negotiation lights up. Configure via:

spring.mvc.contentnegotiation.favor-parameter=true   # allow ?format=xml

For versioned or vendor media types, use custom types like application/vnd.acme.v2+json and route with produces.

The request pipeline: filter vs interceptor vs argument resolver

These three live at different layers, and knowing which to use when is a classic senior distinction:

Servlet container
  └─ Filter chain            ← servlet layer, wraps request/response, runs for EVERY request
       └─ DispatcherServlet
            └─ HandlerInterceptor  ← Spring MVC layer, knows the handler, only mapped requests
                 └─ Controller method
                      ↑ HandlerMethodArgumentResolver builds each method parameter

(The term cross-cutting means a concern that recurs everywhere and isn't specific to one spot — like logging or authentication.)

// FILTER — runs once per request, before Spring MVC even routes
public class TraceIdFilter extends OncePerRequestFilter {
    @Override protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res,
                                              FilterChain chain) throws ServletException, IOException {
        String traceId = Optional.ofNullable(req.getHeader("X-Trace-Id"))
                                 .orElse(UUID.randomUUID().toString());
        MDC.put("traceId", traceId);
        try { chain.doFilter(req, res); }        // MUST call chain to continue
        finally { MDC.clear(); }                 // clean up thread-local, always
    }
}

Note: in a filter you must call chain.doFilter(...) or the request stops right there and never reaches the controller. MDC is a data store stuck to the current thread, used for logging; you clear it in finally so it doesn't leak into the next request on the same thread.

// INTERCEPTOR — has the handler; can short-circuit by returning false
public class AuthInterceptor implements HandlerInterceptor {
    @Override public boolean preHandle(HttpServletRequest req, HttpServletResponse res, Object handler) {
        if (handler instanceof HandlerMethod hm && hm.hasMethodAnnotation(Secured.class)
                && !isAuthenticated(req)) {
            res.setStatus(401);
            return false;                        // stop the chain; controller never runs
        }
        return true;
    }
}

@Configuration
class WebConfig implements WebMvcConfigurer {
    @Override public void addInterceptors(InterceptorRegistry r) {
        r.addInterceptor(new AuthInterceptor()).addPathPatterns("/api/**");
    }
    @Override public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
        resolvers.add(new CurrentUserResolver());
    }
}

The key point about an interceptor is that preHandle can return false and short-circuit the whole chain — the controller never runs at all. Unlike a filter, here the handler object (a HandlerMethod) is in your hands, so you know exactly which method is about to run and what annotations it has.

// ARGUMENT RESOLVER — injects a domain object built from the request
public class CurrentUserResolver implements HandlerMethodArgumentResolver {
    @Override public boolean supportsParameter(MethodParameter p) {
        return p.hasParameterAnnotation(CurrentUser.class);
    }
    @Override public Object resolveArgument(MethodParameter p, ModelAndViewContainer mav,
                                            NativeWebRequest req, WebDataBinderFactory binder) {
        return userService.fromToken(req.getHeader("Authorization"));
    }
}

Actuator & observability

Actuator is a set of ready-made endpoints for viewing the app's health and state in production — like the dashboard and status lights of a control room. spring-boot-starter-actuator adds these under the /actuator path.

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus,loggers
  endpoint:
    health:
      show-details: when-authorized      # never leak component health to anonymous callers
  metrics:
    tags:
      application: shop-api

Key endpoints: health (liveness/readiness groups map to Kubernetes probes — i.e., k8s uses them to know the app is alive and ready for traffic), metrics/prometheus (metrics via Micrometer), loggers (change log levels at runtime, no redeploy!), env, configprops, conditions (the very auto-config report we discussed), httpexchanges, threaddump, heapdump.

Observability in Boot 3 is built on Micrometer Observation. The elegant idea: a single Observation API produces both metrics (numbers and stats) and traces (the trail of a single request through the system) together. Add micrometer-tracing-bridge-otel plus an exporter and every controller, every RestClient, and every @Observed method emits spans with consistent tags (a span is a timed interval in a request's journey).

The embedded server

You used to install a separate server (like Tomcat) and deploy your app's WAR file into it. Spring Boot inverted this: it embeds the server inside the app itself.

Boot 3 embeds Tomcat 10.1 by default (Jetty and Undertow are drop-in alternatives — just exclude spring-boot-starter-tomcat and add the other starter). Key tunables:

server.port=8080
server.tomcat.threads.max=200            # worker threads (blocking model)
server.tomcat.accept-count=100           # OS accept queue when all threads busy
server.tomcat.connection-timeout=20s
server.compression.enabled=true
server.shutdown=graceful                 # drain in-flight requests on shutdown
spring.lifecycle.timeout-per-shutdown-phase=30s

That server.shutdown=graceful (graceful shutdown) means when the app is about to shut down, it first lets in-flight requests finish rather than cutting them off mid-way.

Virtual threads (Java 21+): Tomcat's classic model has a limited pool of threads (say 200); if they're all busy waiting on the database, a new request queues up. A virtual thread is an ultra-lightweight thread the JVM manages, and you can have millions of them. Flip one property to enable it:

spring.threads.virtual.enabled=true      # requires Java 21+

Common pitfalls & gotchas

Keep these as a "frequent mistakes" checklist:

• Exposing JPA entities → LazyInitializationException, N+1, schema leakage. Always map to DTOs.
• @ConditionalOnMissingBean in app code → order-dependent, flaky. Keep it in libraries/auto-config.
• Forgetting ConstraintViolationException when using @Validated param validation — it is not MethodArgumentNotValidException, so a naive advice returns 500 instead of 400.
• @RequestParam on a boolean/primitive with a missing param → 400/500. Use wrapper types + required=false/defaultValue.
• @Transactional on a controller — technically works but muddies layering; keep transactions in the service.
• Self-injection / internal method calls bypassing proxies — calling a @Transactional or @Cacheable method from the same class skips the AOP proxy. Also why @AutoConfiguration's proxyBeanMethods=false matters.
• CORS via a filter and @CrossOrigin → duplicate/conflicting headers. Pick one; prefer central config.
• Exposing all Actuator endpoints (include: "*") in production → info disclosure and DoS.
• Relying on classpath scanning being cheap — @ComponentScan over huge packages slows startup; keep base packages tight.

Best practices

• DTOs as records; validate at the edge; never trust the client.
• Return ProblemDetail for every error; give each problem a stable type URI.
• One @RestControllerAdvice extending ResponseEntityExceptionHandler for the whole app; scope extras only when needed.
• Type-safe @ConfigurationProperties records over scattered @Value.
• Secure and selectively expose Actuator; wire health groups to k8s probes.
• Turn on server.shutdown=graceful and set the container's preStop/terminationGracePeriod accordingly.
• Consider virtual threads (Java 21+) before reaching for reactive, if your bottleneck is blocking I/O and your team knows imperative code.

Interview Questions

Now it's time to cement everything as real interview questions. Answer each one yourself first, then read the answer.

@Service
class OrderService {
    @Transactional
    public void placeOrder(Order o) { save(o); notify(o); }
    @Transactional(propagation = REQUIRES_NEW)
    public void notify(Order o) { /* audit */ }
}

@RestController
class C {
    @GetMapping("/x") String x(@RequestParam boolean flag) { return "" + flag; }
}
// GET /x   (no flag param)