Creating Spring RESTful web services

In this post we will guide you through a pretty simple example to create a RESTful web service using Spring Boot.

To create your application with Spring Boot check out our older post The Spring Boot revolution .


Our RESTful web service will take three parameters in the request and will return a new instance of the infamous class Musician in a JSON format.


Here is the class we will return:

package com.example.entity;

import lombok.Data;

@Data
public class Musician {

    public enum INSTRUMENT{
        GUITAR, DRUMS, BASS, VOICE, KEYBOARDS    
     }

    public Musician(String firstName, String lastName, 
                                INSTRUMENT instrument){
        this.setFirstName(firstName);
        this.setLastName(lastName);
        this.setInstrument(instrument);    
     }


    private String firstName;
    private String lastName;
    private INSTRUMENT instrument;
}

To use the lombok library you will need to add the dependency in your pom file.

<dependencies>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>    
        <optional>true</optional>
    </dependency>
</dependencies>

Here is our controller. Any Spring  @RestController in a Spring Boot application should render a JSON response by default as long as Jackson2 is on the classpath ( it's included when you add the spring-boot-starter-web to your pom file).

package com.example.hello;

import com.example.entity.Musician;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@SpringBootApplication
public class HelloController {


    @RequestMapping("/greeting")
    public Musician greeting(@RequestParam(value="firstName", 
                              defaultValue = "Peter") String firstName,                                 @RequestParam(value="lastName", 
                              defaultValue = "Gabriel") String lastName,                                @RequestParam(value="instrument", 
                              defaultValue = "VOICE") String instrument){

        return new Musician(firstName, lastName, 
                 Musician.INSTRUMENT.valueOf(instrument));    
     }


    public static void main(String[] args) throws Exception {
        SpringApplication.run(HelloController.class);    
}

}

We've changed the @EnableAutoConfiguration annotation for the @SpringBootApplication  . The @SpringBootApplication  annotation is equivalent to using @Configuration , @EnableAutoConfiguration and  @ComponentScan  with their default attributes.

The @RequestMapping annotation makes sure HTTP requests to  /greeting  are mapped to the  greeting()  method. ( @RequestMapping maps all HTTP operations by default GET, PUT, POST, etc. )

The @RequestParam  binds the value of the query String parameters  firstName   ,lastName   and instrument  into the parameters of the same name in the greeting()  method.

The implementation of the body method creates and returns a new instance of Musician with the same values for firstName ,  lastName  and  instrument  as the ones we set on the request.

One thing worth mentioning is the main difference between a classic MVC controller and our RESTful web service controller:  how the HTTP response body is created.
Instead of relying on a view technology to render the greeting information on a HTML page, this RESTful web service controller simply creates, populates and returns a  Musician object . The object data will be written directly to the HTTP response as JSON.

This Spring 4's new @RestController annotation marks the class as a controller where every method will return a domain object instead of a view.  This annotation includes @Controller and @ResponseBody together.

Enough talk, now start your app with

$ mvn spring-boot:run

Open your browser on:

http://localhost:8080/greeting

and you will see

{
firstName: "Peter",
lastName: "Gabriel",
instrument: "VOICE"






}

Now, let's try another guy from the band. Add the values you want on the request, for example, Tony Banks, a great keyboard player. These values will overwrite the values set by  defaultValue on @RequestParam .

http://localhost:8080/greeting?firstName=Tony&lastName=Banks&instrument=KEYBOARDS

then you'll see:

{
firstName: "Tony",
lastName: "Banks",
instrument: "KEYBOARDS"


}

Here's an interesting link if you want further information: Building a RESTful web service with Spring.
You can tap yourself on your shoulder, good work! You've just created a RESTful web service using Spring 4.

That's it for today ! Enjoy.