:spring_version: current :toc: :project_id: gs-rest-service :icons: font :source-highlighter: prettify
This guide walks you through the process of creating a "
Hello, World" RESTful web
service with Spring.
== What You Will Build
You will build a service that will accept HTTP GET requests at
It will respond with a JSON representation of a greeting, as the following listing shows:
You can customize the greeting with an optional
name parameter in the query string, as
the following listing shows:
name parameter value overrides the default value of
World and is reflected in the
response, as the following listing shows:
== What You Need
:java_version: 1.8 include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/main/prereq_editor_jdk_buildtools.adoc
[[scratch]] == Starting with Spring Initialize
If you use Maven, visit the https://start.spring.io/#!type=maven-project&language=java&platformVersion=2.4.3.RELEASE&packaging=jar&jvmVersion=1.8&groupId=com.example&artifactId=rest-service&name=rest-service&description=Demo%20project%20for%20Spring%20Boot&packageName=com.example.rest-service&dependencies=web[Spring Initializr] to generate a new project with the required dependency (Spring Web).
The following listing shows the
pom.xml file that is created when you choose Maven:
If you use Gradle, visit the https://start.spring.io/#!type=gradle-project&language=java&platformVersion=2.4.3.RELEASE&packaging=jar&jvmVersion=1.8&groupId=com.example&artifactId=rest-service&name=rest-service&description=Demo%20project%20for%20Spring%20Boot&packageName=com.example.rest-service&dependencies=web[Spring Initializr] to generate a new project with the required dependency (Spring Web).
The following listing shows the
build.gradle file that is created when you choose Gradle:
=== Manual Initialization (optional)
If you want to initialize the project manually rather than use the links shown earlier, follow the steps given below:
. Navigate to https://start.spring.io. This service pulls in all the dependencies you need for an application and does most of the setup for you. . Choose either Gradle or Maven and the language you want to use. This guide assumes that you chose Java. . Click Dependencies and select Spring Web. . Click Generate. . Download the resulting ZIP file, which is an archive of a web application that is configured with your choices.
NOTE: If your IDE has the Spring Initializr integration, you can complete this process from your IDE.
[[initial]] == Create a Resource Representation Class
Now that you have set up the project and build system, you can create your web service.
Begin the process by thinking about service interactions.
The service will handle
GET requests for
/greeting, optionally with a
in the query string. The
GET request should return a
200 OK response with JSON in the
body that represents a greeting. It should resemble the following output:
id field is a unique identifier for the greeting, and
content is the textual
representation of the greeting.
To model the greeting representation, create a resource representation class. To do so,
provide a plain old Java object with fields, constructors, and accessors for the
content data, as the following listing (from
Greetinginto JSON. Jackson is included by default by the web starter.
== Create a Resource Controller
In Spring's approach to building RESTful web services, HTTP requests are handled by a
controller. These components are identified by the
annotation, and the
GreetingController shown in the following listing (from
/greeting by returning a new instance of the
This controller is concise and simple, but there is plenty going on under the hood. We break it down step by step.
@GetMapping annotation ensures that HTTP GET requests to
/greeting are mapped to the
NOTE: There are companion annotations for other HTTP verbs (e.g.
@PostMapping for POST). There is also a
@RequestMapping annotation that they all derive from, and can serve as a synonym (e.g.
@RequestParam binds the value of the query string parameter
name into the
parameter of the
greeting() method. If the
name parameter is absent in the request,
World is used.
The implementation of the method body creates and returns a new
Greeting object with
content attributes based on the next value from the
counter and formats the
name by using the greeting
A key difference between a traditional MVC controller and the RESTful web service
controller shown earlier is the way that the HTTP response body is created. Rather than
relying on a view technology to perform server-side rendering of the greeting data to
HTML, this RESTful web service controller populates and returns a
Greeting object. The
object data will be written directly to the HTTP response as JSON.
This code uses Spring
annotation, which marks the class as a controller where every method returns a domain
object instead of a view. It is shorthand for including both
Greeting object must be converted to JSON. Thanks to Spring's HTTP message converter
support, you need not do this conversion manually. Because
https://github.com/FasterXML/jackson[Jackson 2] is on the classpath, Spring's
is automatically chosen to convert the
Greeting instance to JSON.
Logging output is displayed. The service should be up and running within a few seconds.
== Test the Service
Now that the service is up, visit
http://localhost:8080/greeting, where you should see:
name query string parameter by visiting
http://localhost:8080/greeting?name=User. Notice how the value of the
attribute changes from
Hello, World! to
Hello, User!, as the following listing shows:
This change demonstrates that the
@RequestParam arrangement in
working as expected. The
name parameter has been given a default value of
can be explicitly overridden through the query string.
Notice also how the
id attribute has changed from
2. This proves that you are
working against the same
GreetingController instance across multiple requests and that
counter field is being incremented on each call as expected.
Congratulations! You have just developed a RESTful web service with Spring.
== See Also
The following guides may also be helpful: