Introductory Spring Boot Rest Service

“The only true wisdom is in knowing you know nothing.”
― Socrates

1. Introduction

Getting started with Spring and Spring Boot? Welcome!

This is a beginner level tutorial for implementing a Hello World REST Service using Spring Boot. The emphasis is on getting the basic application outline worked out. One to which we can add various enterprise features in further articles.

The example presented is simple REST controller which returns a message to the user.

2. The Directory Structure

The minimum directory structure for building with Maven is shown below.

3. Building with Maven

Here is the complete build configuration for maven: pom.xml. We are using Spring Boot 1.5.2.RELEASE version with spring-boot-starter-web.

<project xmlns="http://maven.apache.org/POM/4.0.0"
	 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
			     http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>sample</groupId>
  <artifactId>sample1</artifactId>
  <version>0.1.0-SNAPSHOT</version>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <javac.target>1.8</javac.target>
  </properties>

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>1.5.2.RELEASE</version>
    <relativePath/>
  </parent>
  
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.1</version>
        <configuration>
          <compilerVersion>${javac.target}</compilerVersion>
          <source>${javac.target}</source>
          <target>${javac.target}</target>
	  <compilerArgument>-Xlint</compilerArgument>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
      <plugin>
        <artifactId>maven-clean-plugin</artifactId>
        <version>2.5</version>
        <configuration>
          <filesets>
            <fileset>
              <directory>.</directory>
              <includes>
                <include>**/*~</include>
              </includes>
            </fileset>
          </filesets>
        </configuration>
      </plugin>
    </plugins>
  </build>

  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
  </dependencies>

</project>

4. The Web Controller

The controller implementation is as basic as it gets. It composes a message to the user, inserts it into a map and returns it. The map is serialized to JSON by Spring.

package sample;

import java.util.Map;
import java.util.HashMap;

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

@RestController
public class SampleController {

    @RequestMapping("/sample")
    public Map<String,String> sample(@RequestParam(value="name", defaultValue="World") String name) {
	Map<String,String> result = new HashMap<>();
	result.put("message", String.format("Hello, %s", name));
	return result;
    }
}

5. The Main Routine

The main program initializes Spring and hands over the control. The main class also adds a RequestMapping to the context root of the application.

package sample;

import org.springframework.http.MediaType;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.ResponseBody;

@RestController
@SpringBootApplication
public class sample1
{
    @RequestMapping(value = "/", produces = MediaType.TEXT_HTML_VALUE)
    public String home() {
        return "Nothing here. Go to <a href='/sample'>/sample</a>";
    }

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

6. Building and Running

Build the project using the command line as follows:

$ mvn clean package

Run the program as follows. The Spring MVC framework takes care of starting a Web Server listening on the localhost at port 8080 by default.

$ java -jar target/sample1-0.1.0-SNAPSHOT.jar

Check the application by surfing to http://localhost:8080. It should show the following message.

Clicking the link (http://localhost:8080/sample) should show the JSON output.

{"message":"Hello, World"}

7. Changing the Server and Port

To change the port on which the web server needs to listen, start the program as follows:

$ java -Dserver.port=9090 -jar target/sample1-0.1.0-SNAPSHOT.jar

The web server listens on the local loopback network interface. To change it to listen on all network interfaces, invoke the program as follows:

java -Dserver.address=0.0.0.0 -jar target/sample1-0.1.0-SNAPSHOT.jar

Summary

This article presented a basic “Hello World” Spring MVC tutorial. We added a simple web controller as well as a main program which invokes the Spring Framework. In further articles, we will explore other aspects of the Spring Framework.