Chapter 10: Implementing REST endpoints
The introduction explains why AI-generated REST services need careful review and previews the chapter’s endpoint topics.
After this chapter you will be able to
- AI Generated REST Verification. Explain why developers must check the requests and responses of AI-generated REST services.
- REST communication between apps. Explain that REST lets a client call functionality a server exposes through endpoints, whether the client is a web app, mobile app, or another backend service.
- Spring MVC REST response flow. Describe a Spring REST endpoint as a controller action mapped to an HTTP method and path, and distinguish its response flow from one that resolves a view.
- REST call failure considerations. Explain why REST calls can fail or strain an app, and describe the questions to consider about data consistency and user-facing errors when they do.
- REST endpoint response behavior. Explain how a controller action becomes a basic REST endpoint: @Controller makes the class a Spring MVC controller, @GetMapping maps an action to an HTTP path and method, and @ResponseBody makes its return value response data rather than a view name.
- Class-level REST controller annotation. Explain why the example replaces repeated method-level @ResponseBody annotations with @RestController on the class, and describe what that annotation combines.
- Basic endpoint testing tools. Describe how Postman and cURL can call a running endpoint, including the GUI versus command-line distinction and the cURL options mentioned for specifying an HTTP method or showing more details.
- HTTP response parts. Explain that a backend sends an HTTP response to a client in reply to a request, and distinguish the roles of response headers, body, and status.
- Objects as response bodies. Explain that a controller action sends an object to the client by returning it, and identify an object used to transfer data between apps as a data transfer object (DTO).
- Default JSON representation. Describe how Spring represents returned objects in the response body by default and state that a controller can also return a collection of objects.
- Default HTTP response statuses. Explain what the common HTTP response statuses listed here signal about a request’s result.
- Custom responses with ResponseEntity. Describe how a controller action uses ResponseEntity to set an HTTP response’s body, status, and headers, and identify what the example changes.
- Exception-specific HTTP responses. Explain how the payment endpoint returns different HTTP responses for a successful payment and a NotEnoughMoneyException, including the status and body in each case.
- Separated exception handling. Justify moving exception handling from controller actions into REST controller advice, and describe what remains in the controller.
- REST advice exception handlers. Describe how a REST controller advice selects logic for a particular exception and how that logic can receive the exception instance.
- Request Body Parameter Binding. Describe how @RequestBody lets a controller action receive a JSON request body as a parameter, and what happens if Spring cannot decode it.
What it builds on
- Using the GET and POST HTTP methods (chapter 8) · Mapping controller actions to HTTP methods in a Spring web app.
- Implementing a web app with Spring MVC (chapter 7) · The Spring MVC flow used for web apps.
- How aspects work in Spring (chapter 6) · The idea of an aspect intercepting application behavior
Section by section
Introduction
The introduction explains why AI-generated REST services need careful review and previews the chapter’s endpoint topics.
- AI Generated REST Verification: Explain why developers must check the requests and responses of AI-generated REST services.
Why it matters: Checking generated endpoints helps catch problems that could make an app malfunction or expose it to security risks.
Key terms: REST services, shapes of requests and responses, security vulnerabilities
10.1 Using REST services to exchange data between apps
This section explains how REST services connect apps through Spring MVC endpoints and why those calls must be designed with possible failures in mind.
- REST communication between apps: Explain that REST lets a client call functionality a server exposes through endpoints, whether the client is a web app, mobile app, or another backend service.
Why it matters: It gives you a way to recognize where REST fits when two apps need to communicate. - Spring MVC REST response flow: Describe a Spring REST endpoint as a controller action mapped to an HTTP method and path, and distinguish its response flow from one that resolves a view.
Why it matters: It connects REST endpoints to the Spring MVC controller mappings you have already used while clarifying what changes in the response. - REST call failure considerations: Explain why REST calls can fail or strain an app, and describe the questions to consider about data consistency and user-facing errors when they do.
Why it matters: A simple endpoint is not enough if a failed call can leave data inconsistent or an error unexplained to the user.
Key terms: REST services, endpoint, client, server, REST endpoint, controller action, HTTP method, path, dispatcher servlet, view resolver
10.2 Implementing REST endpoints
This section shows how to turn a Spring MVC controller action into a REST endpoint and how to call basic endpoints with Postman or cURL.
- REST endpoint response behavior: Explain how a controller action becomes a basic REST endpoint: @Controller makes the class a Spring MVC controller, @GetMapping maps an action to an HTTP path and method, and @ResponseBody makes its return value response data rather than a view name.
Why it matters: The difference between returning a view name and returning response data is central to this first REST endpoint. - Class-level REST controller annotation: Explain why the example replaces repeated method-level @ResponseBody annotations with @RestController on the class, and describe what that annotation combines.
Why it matters: It provides the same endpoint behavior while avoiding a repeated annotation on every action. - Basic endpoint testing tools: Describe how Postman and cURL can call a running endpoint, including the GUI versus command-line distinction and the cURL options mentioned for specifying an HTTP method or showing more details.
Why it matters: Calling an endpoint lets you check what the running application actually returns.
Key terms: Spring MVC, @Controller, @GetMapping, @ResponseBody, view name, HTTP response, @RestController, code duplication, Postman, cURL
10.3 Managing the HTTP response
Introduces the HTTP response as the backend’s reply to a client request and identifies its three parts.
- HTTP response parts: Explain that a backend sends an HTTP response to a client in reply to a request, and distinguish the roles of response headers, body, and status.
Why it matters: These distinctions help you describe what an endpoint sends back to its client.
Key terms: HTTP response, response headers, response body, response status
10.3.1 Sending objects as a response body
This section shows how a REST controller returns objects or collections in an HTTP response body, which Spring formats as JSON by default.
- Objects as response bodies: Explain that a controller action sends an object to the client by returning it, and identify an object used to transfer data between apps as a data transfer object (DTO).
Why it matters: This is the basic way an endpoint sends structured data rather than a view to its client. - Default JSON representation: Describe how Spring represents returned objects in the response body by default and state that a controller can also return a collection of objects.
Why it matters: It explains what a client normally receives when an endpoint returns Java objects. - Immutable payload recommendation: Explain why the author recommends records for HTTP request and response data when constraints permit.
Why it matters: It gives a design preference for the data objects exchanged at an application’s boundary.
Key terms: controller’s action, HTTP response body, data transfer object (DTO), Country, JSON, response body, List, custom converter, records, immutable data carriers
10.3.2 Setting the response status and headers
This section explains what HTTP response statuses and headers communicate and how a Spring controller can customize them with ResponseEntity.
- Default HTTP response statuses: Explain what the common HTTP response statuses listed here signal about a request’s result.
Why it matters: The status gives the client a quick indication of how the request turned out. - Custom responses with ResponseEntity: Describe how a controller action uses ResponseEntity to set an HTTP response’s body, status, and headers, and identify what the example changes.
Why it matters: ResponseEntity lets an endpoint communicate more than a response body alone.
Key terms: response status, 200 OK, 404 Not Found, 400 Bad Request, 500 Error on server, ResponseEntity, response body, response headers, 202 Accepted
10.3.3 Managing exceptions at the endpoint level
The section shows how to turn endpoint exceptions into informative HTTP responses, move exception handling into REST controller advice, and use a contract-first approach to define REST APIs.
- Exception-specific HTTP responses: Explain how the payment endpoint returns different HTTP responses for a successful payment and a NotEnoughMoneyException, including the status and body in each case.
Why it matters: An error response tells the client what went wrong rather than leaving it with the successful-payment response. - Separated exception handling: Justify moving exception handling from controller actions into REST controller advice, and describe what remains in the controller.
Why it matters: Centralizing exception logic makes shared error handling easier to maintain and find. - REST advice exception handlers: Describe how a REST controller advice selects logic for a particular exception and how that logic can receive the exception instance.
Why it matters: These annotations connect a thrown controller exception to the separate code that handles it. - Contract-first endpoint generation: Explain the contract-first approach described in the sidebar, including what the contract specifies, what is generated, and why teams may use it.
Why it matters: A shared API description can guide implementation and communication before teams write all the endpoint code. - Reviewed contract generation: Describe the recommended order for using AI with a contract-first endpoint and why the contract is reviewed before generating implementation code.
Why it matters: Checking the contract before code generation can catch API design mistakes before they spread into the implementation.
Key terms: ResponseEntity, NotEnoughMoneyException, PaymentDetails, ErrorDetails, 400 Bad Request, REST controller advice, controller action, exception management, @RestControllerAdvice, @ExceptionHandler
10.4 Using a request body to get data from the client
This section explains how a REST endpoint receives client data from an HTTP request body and why request bodies are generally avoided with GET.
- Request Body Purpose: Explain that a client can send data to a REST endpoint in the HTTP request body, especially when the data is relatively large.
Why it matters: It helps you choose where to put data a client sends to a REST endpoint. - Request Body Parameter Binding: Describe how @RequestBody lets a controller action receive a JSON request body as a parameter, and what happens if Spring cannot decode it.
Why it matters: It explains both how a controller gets data from the request body and why an undecodable body is rejected. - GET Request Body Caveat: Distinguish between the current specification allowing a body on an HTTP GET request and the section’s recommendation not to use one in general.
Why it matters: It prevents confusing what HTTP permits with what is practical and recommended for GET endpoints.
Key terms: HTTP request body, REST endpoints, @RequestBody, JSON, parameter type, 400 Bad Request, PaymentDetails, HTTP GET, request body, cacheable
10.5 Questions
This section lists review questions for checking understanding of REST endpoints and points readers to Appendix A for answers.
10.6 Summary
The section summarizes how Spring MVC REST endpoints exchange data, produce HTTP responses, and handle exceptions.
Where this is used later
- Calling REST endpoints using RestClient (chapter 11) · Calling REST endpoints depends on recognizing the client’s role in this communication.
- (chapter intro) (chapter 11) · REST services exchange data between apps.
- What do you need to know? (chapter 11) · Assumes familiarity with apps exchanging data through REST services.
- Implementing controller integration tests (chapter 16) · request bodies supply data to REST endpoints
Concepts explained in this chapter
- ResponseEntityResponseEntity is a Spring type that represents an HTTP response together with its body, status, and headers.
- endpointAn endpoint is a network-accessible interface through which a service exposes or consumes an operation or resource.
- @RestControllerAdvice@RestControllerAdvice is a Spring annotation for applying shared advice, including exception handling, to REST controllers.
- @ExceptionHandlerThe @ExceptionHandler annotation identifies a method that handles specified exceptions thrown during controller request processing.
- design-first approachA contract-first approach develops an API by specifying its interface before implementing the endpoint and generating implementation artifacts from that specification.
- OpenAPI specificationOpenAPI is a standard, machine-readable specification format for describing HTTP APIs, including their operations, inputs, and responses.
- exception handlerAn exception handler is a method that defines the response or other processing performed for a particular exception.
- @responsebodyThe @ResponseBody annotation declares that a controller action returns data directly in the HTTP response rather than a view name.
- restcontroller annotationThe @RestController annotation marks a Spring MVC controller whose actions return response data directly and are treated as REST endpoints.
- JSONJSON is a text-based data-interchange format that represents structured data using objects, arrays, values, and name-value pairs.
- HTTP responseAn HTTP response is a message returned by an HTTP server containing a status and optional headers and content.
- RESTREST is an architectural style for designing networked resources and their interactions through representations and standardized operations.
- PostmanPostman is a software tool with a graphical interface for creating, sending, and inspecting HTTP requests and responses.
- curlcURL is a command-line tool and library for transferring data using network protocols including HTTP.
- rest apiA network-accessible service that exposes resources and operations according to REST constraints.
- payloadAn HTTP request body is the payload portion of a request that carries data sent by the client.
- web API action methodA controller action is a controller method associated with an HTTP request and responsible for producing the request's response.
- data transfer objectA data transfer object is an object that carries structured data between software applications or application boundaries.
- Spring MVCSpring MVC is the Spring web framework for developing applications that handle HTTP requests.
- exceptionAn exception signals an abnormal condition that can be thrown during execution and handled by a caller or interceptor.
- DispatcherServletA dispatcher servlet is the Spring MVC servlet that receives web requests and coordinates their dispatch to controller actions and response rendering.
- data inconsistencyA data inconsistency is a condition in which related stored or exchanged data does not agree or satisfy the application's consistency rules.
- view resolverA view resolver is a Spring MVC component that locates a view from the name returned by a controller action.
- immutabilityImmutability is the property that an object's state cannot be changed after initialization.
- @ControllerThe @Controller annotation marks a class as a Spring MVC controller component eligible for management by Spring.
- HTTP headerAn HTTP header is a metadata field in an HTTP request or response that conveys information about the message or its handling.
- HTTP request parameterAn HTTP request parameter is a named value supplied with a request, such as in its query string or submitted form data.
- path variableA path variable is a value conveyed within a request path, typically as a variable segment of a resource URI.
- viewA view is the presentation resource whose content is rendered and returned as a web response.
- controllerA controller in Spring MVC is an application component that receives and handles web requests and produces responses.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
