How to create RESTful web services with Spring

When we are dealing with RESTful web services, we need to be using @RestController annotation which basically represents the @Controller and @ResponseBody annotations.

When we use @RequestMapping for our methods, we can add an attribute which is called produces which specifies that the output sent to the user will be in JSON format.

Example

Employee.java

public class Employee {
   private int id;
   private String firstName;
   private String lastName;

   public Employee(int id, String firstName, String lastName) {
      this.id = id;
      this.firstName = firstName;
      this.lastName = lastName;
   }

   public setFirstName(String fName) {
      firstName = fName;
   }

   public setLastName(String lName) {
      lastName = lName;
   }
   
   public int getId() {
      return id;
   }
   
   public String getFirstName() {
      return firstName;
   }
   
   public String getLastName() {
      return lastName;
   }
}

EmployeeController.java

The controller class will be resposnible for handling the HTTP requests, that is a convention when we build RESTful web services.

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class EmployeeController {
    @RequestMapping("/employee")
    public Employee createEmployee(@RequestParam(value="id") int employeeId, @RequestParam(value="firstName") String fName, @RequestParam(value="lastName") String lName) {		
	// return the new Employee object with that id, first name and last name
	return new Employee(employeeId, fName, lName);
    }
}

Let’s break down the Controller class. It look simple as first sight, and it is, however there is a lot of stuff happening behind the scenes. Let me explain exactly what.

Thanks to @RequestMapping, we mapped the path “/employee” to our getEmployeeId method and if you are not familiar with @RequestMapping annotation, when we do not specify the method request, it maps all the HTTP operations by default. If we wanted to have it as a GET method only (which is preferrably in our example) we would change the above code to the following:

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class EmployeeController {    
    @RequestMapping("/employee", method=RequestMethod.GET)
    public Employee createEmployee(@RequestParam(value="id") int employeeId, @RequestParam(value="firstName") String fName, @RequestParam(value="lastName") String lName) {        		
	// return the new Employee object with that id, first name and last name 
        return new Employee(employeeId, fName, lName);
    }
}

So now we changed the @RequestMapping annotation to @RequestMapping(“/employee”, method=RequestMethod.GET). As I said in the beginning of this tutorial, we cal also specify that we want the result to be in JSON format. So we can change @RequestMapping(“/employee”, method=RequestMethod.GET) to @RequestMapping(“/employee”, method=RequestMethod.GET, produces=”application/json”). 

We extracted the query parameter “id” and into “employeeId”, “firstName” into “fName” and “lastName” into “lName”, and then we instantiate a new Employee object and pass that id, first name and last name that we got as query parameters.

To retrieve those parameters and create the Employee object using this method, the URL will look like:

http://localhost:8080/employee?id=x&firstName=xx&lastName=xxx

And again, thanks to @RequestParam, we get those x’s and store them into the method parameters.

Run the application

To run the application, we will be using main() method which will look like:

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

The SpringApplication.run() launches the application and does everything from you. This is the simplest way, however if you prefer, you can make it as an executable JAR or run it from the command line with Gradle or Maven. Your choice.

The response

The response body of the JSON format will looke like:

{
   "id":x, firstName="xx", lastName="xxx"
}