LearnAI ToolsCareerPractice BuildsPlayContact
Lesson 624 min read

Web & REST API Dependencies

A catalog of spring-boot-starter-web, spring-boot-starter-webflux, spring-boot-starter-web-services, and spring-boot-starter-hateoas, with use cases and working examples.

Introduction

This lesson opens the dependency catalog with the category almost every Spring Boot project touches: exposing an API over HTTP. Four related dependencies cover most needs here, from traditional REST controllers to reactive streaming APIs to legacy SOAP services.

spring-boot-starter-web

Use case: building traditional, synchronous REST controllers and MVC web applications, backed by an embedded Tomcat server. This is the default choice for the vast majority of Spring Boot APIs.

pom.xml
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
ProductController.java
@RestController
@RequestMapping("/api/products")
public class ProductController {


    @GetMapping("/{id}")
    public ProductDto getProduct(@PathVariable Long id) {
        return new ProductDto(id, "Wireless Mouse", 799);
    }
}
GET /api/products/1

Click Run to see what this code prints.

spring-boot-starter-webflux

Use case: building reactive, non-blocking APIs that can handle a very large number of concurrent connections with a small thread pool, using Project Reactor's `Mono` (0 or 1 value) and `Flux` (0..N values) types. Choose this when your workload is I/O-heavy (many slow downstream calls) rather than CPU-heavy.

pom.xml
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>
ProductReactiveController.java
@RestController
@RequestMapping("/api/products")
public class ProductReactiveController {


    @GetMapping("/{id}")
    public Mono<ProductDto> getProduct(@PathVariable Long id) {
        return Mono.just(new ProductDto(id, "Wireless Mouse", 799));
    }


    @GetMapping
    public Flux<ProductDto> getAllProducts() {
        return Flux.just(
            new ProductDto(1L, "Wireless Mouse", 799),
            new ProductDto(2L, "Mechanical Keyboard", 3499)
        );
    }
}
GET /api/products (streamed)

Click Run to see what this code prints.

starter-web vs starter-webflux

Aspectspring-boot-starter-webspring-boot-starter-webflux
Programming modelSynchronous, blocking (Servlet API)Asynchronous, non-blocking (Reactive Streams)
Embedded serverTomcat (default)Netty (default)
Return typesPlain objects, ResponseEntityMono<T>, Flux<T>
Best forMost typical CRUD REST APIsHigh-concurrency, I/O-heavy, streaming workloads
Learning curveLower — familiar imperative codeHigher — reactive operators and backpressure

spring-boot-starter-web-services

Use case: exposing or consuming SOAP-based web services, still common in enterprise, government, and banking integrations that have not migrated to REST. It builds on Spring-WS to marshal XML requests and responses.

pom.xml
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web-services</artifactId>
</dependency>
CountryEndpoint.java (simplified SOAP endpoint)
@Endpoint
public class CountryEndpoint {


    private static final String NAMESPACE_URI = "http://programinds.com/countries";


    @PayloadRoot(namespace = NAMESPACE_URI, localPart = "getCountryRequest")
    @ResponsePayload
    public GetCountryResponse getCountry(@RequestPayload GetCountryRequest request) {
        GetCountryResponse response = new GetCountryResponse();
        response.setCountry(new Country("India", "New Delhi"));
        return response;
    }
}
When You Would Actually Use This

Reach for starter-web-services almost exclusively when integrating with an existing external SOAP endpoint (e.g. a government or banking API) that you cannot change. New, greenfield APIs should default to REST via starter-web instead.

spring-boot-starter-hateoas

Use case: building hypermedia-driven REST APIs, where responses include not just data but also links describing what related actions or resources the client can navigate to next (the HATEOAS principle — Hypermedia As The Engine Of Application State).

pom.xml
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-hateoas</artifactId>
</dependency>
ProductHateoasController.java
@RestController
@RequestMapping("/api/products")
public class ProductHateoasController {


    @GetMapping("/{id}")
    public EntityModel<ProductDto> getProduct(@PathVariable Long id) {
        ProductDto product = new ProductDto(id, "Wireless Mouse", 799);
        return EntityModel.of(product,
            linkTo(methodOn(ProductHateoasController.class).getProduct(id)).withSelfRel(),
            linkTo(methodOn(ProductHateoasController.class).getAllProducts()).withRel("all-products"));
    }
}
GET /api/products/1

Click Run to see what this code prints.

Common Mistakes

Avoid These Mistakes
  • Adding both spring-boot-starter-web and spring-boot-starter-webflux to the same application — they configure competing embedded servers and Spring Boot will not know which one to start.
  • Choosing WebFlux for a typical low-traffic CRUD app "because reactive sounds faster" — for most workloads, the added complexity outweighs the benefit.
  • Using starter-web-services for a brand-new API when a plain REST controller (starter-web) would be simpler and more widely understood.

Best Practices

  • Default to spring-boot-starter-web unless you have a specific, measured need for reactive, non-blocking I/O.
  • Only reach for starter-hateoas when clients genuinely benefit from discoverable, self-describing responses — it adds response complexity.
  • Keep SOAP integrations isolated in their own module or package, since they use a very different programming model from REST controllers.

Frequently Asked Questions

You can, but doing so blocks the reactive event loop thread, defeating the purpose of WebFlux. For genuinely reactive database access you would pair it with R2DBC or a reactive MongoDB driver instead.

Strictly by Roy Fielding's original definition, yes, but in practice most production REST APIs skip hypermedia links for simplicity, and starter-hateoas is used only when discoverability is genuinely valuable to API consumers.

No, it is specifically for SOAP/XML-based web services built with Spring-WS; for REST you use spring-boot-starter-web instead.

Key Takeaways

  • spring-boot-starter-web is the default choice for synchronous REST APIs, backed by embedded Tomcat.
  • spring-boot-starter-webflux is for reactive, non-blocking, high-concurrency workloads, backed by Netty.
  • spring-boot-starter-web-services is for SOAP/XML integrations, typically with legacy or enterprise systems.
  • spring-boot-starter-hateoas adds hypermedia links to REST responses for discoverable APIs.

Summary

These four dependencies cover the vast majority of how Spring Boot applications expose functionality over HTTP, from simple REST endpoints to reactive streams to legacy SOAP integrations. Next, you will look at two more specialized communication styles: WebSocket for real-time data and GraphQL for flexible, client-driven queries.

Next Lesson →

WebSocket & GraphQL Dependencies