Request Mapping | Spring Boot - Building Restful Web Services
Overview
To interact with a resource on the web, we need its address on the web and have some way of requesting or manipulating it. The web provides a URL (uniform resource locator) to make a resource addressable. A URL is composed of 3 parts.
- Protocol :
Protocol can be HTTP, FTP, etc. - Resource Address :
The location of the server was resolved using the IP address. - Resource :
Resource being requested or manipulated.
Let’s see the three parts with this example URL :
- Protocol is HTTPS.
- Resource Address is en.wikipedia.org resolved using DNS.
- Resource is /wiki/World_Wide_Web.
It’s the responsibility of the machine “listening” at en.wikipedia.org to map the remainder of the URL, /wiki/World_Wide_Web, to the actual resource.
Request Mapping Basics
@RequestMapping is Spring MVC's most common and widely used annotation. It is used to map web requests onto specific handler classes and methods and make web resources addressable.
Annotation has the following optional attributes.
- Name :
Assign a name to this mapping. - value :
The primary mapping expressed by this annotation. - method :
The HTTP request methods to map to - headers :
The headers of the mapped request, narrowing the primary mapping.
All the attributes in the annotation narrows/restrict the mapping to specific criteria.
Request Mapping — by Path
Let's start with a simple example : An /hello mapping mapped to the hello() method on the controller.
Invoking the /hello API will result in the below response.
Request Mapping — the HTTP Method
If no HTTP method is specified in the request mapping, it maps to all the HTTP verbs. The same mapping can be invoked with POST, PUT and DELETE operations.
If we want to restrict mapping to one HTTP Verb, we need to provide it using the HTTP Method inside the @RequestMapping annotation.
The above code will restrict invocation to only the HTTP Get method. Invoking endpoint using another verb results in 405 - Method not allowed.
Request Mapping and HTTP Headers
Providing HTTP headers restricts mapping to specific HTTP headers, and the handler will be invoked only if configured headers are provided in the request.
With the Headers Attribute
Let's restrict mapping to specific headers.
The above handler will be invoked if headers foo=bar is supplied with the request.
With incorrect header :
With correct headers :
Request Mapping Consumes and Produces
Mapping can be narrowed down on what type and format of input handler consume and produces. For example, we can restrict mapping to consuming JSON type and producing JSON type. Request mapping has two special attributes for it.
- Consume :
Specify the mime type that is accepted. - Produces :
Specify what is being produced so that browser and client can render it properly.
Let's restrict our mapping to produce only JSON responses. The invocation will be successful if the content expectation from the caller matches with the API.
A caller requesting XML from our API will result in the response 406 - Not acceptable
Invoke with accept application/xml will result in
Involving with accept headers application/JSON should be successful.
Request Mapping with Path Variables
RESTful services use URIs to name resources. To facilitate accessing the information in a URI, its structure follows conventions so that it can easily be described in a parameterized form.
For example, the URI Template http://www.example.com/employee/{employeeId} contains a variable employee. If we assign the variable the value "bob", then 'expanding' the URI Template gives.
Spring boot provides @PathVariable annotation, which extracts the required variable provided in the URI.
Single Path Variable
A simple example with a single path variable :
Invoking method with the different variables will act according to the input variable.
Multiple Path Variable
A more complex URI may need to map multiple parts of the URI to multiple values :
Invoking API with id = 99 and name = bob.
Request Mapping with Request Parameters
Similar to path variables or user input can be provided using request parameters using the @RequestParam annotation.
The URI and response will be with the request parameter.
Don't miss the chance to become a Spring Boot expert. Enroll in our Java Spring Boot course and gain the skills to create modern and efficient Java projects.
Conclusion
In this article, we covered :
- @RequestMapping annotation in Spring with a different combination.
- @RequestMapping with HTTP headers.
- Provide mime type in request mapping using consume and produces attributes.
- Binding parts of the URI with @PathVariable
- and working with URI parameters and the @RequestParam annotation.