What I Learned at Work this Week: Spring Boot Controllers and Annotations

Loyal readers know that I have some pretty great coworkers. I came across a perfect example this week when I asked a coworker to explain what they were working on and they decided to take an hour to hold an information session for the whole team. I learned a lot so, in the interest of solidifying my understanding, I’ll be writing about one of the core concepts of an API: Controllers.

What is an API Controller?

APIs work by sending and receiving requests. When a request is received by an API, it’s up to the Controller to execute the desired logic. At work, we were using Java Spring Boot — a super simple Spring Boot Controller might look something like this:

package com.example.sampleapp.blog;import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class GreetingController {
@RequestMapping("/")
public String getGreeting() {
return "Good Afternoon Medium.";
}
}

The first line is the package declaration, which is the location of our class (we need this more or less because Java wants us to). Next come a pair of imports: RequestMapping and RestController. As we can see, those are later used as annotations, which can be identified with the @ symbol. If you’re new to Spring Boot like me, you might not recognize this syntax. So what’s an annotation?

Spring Boot Annotations

Spring Boot Annotations is a form of metadata that provides data about a program. In other words, annotations are used to provide supplemental information about a program. It is not a part of the application that we develop. It does not have a direct effect on the operation of the code they annotate. It does not change the action of the compiled program.

Annotations are definitely helpful in categorizing classes and methods. They can be placed right before our declaration to indicate the purpose of the subsequent logic. But I was (and actually still am) confused by this document’s insistence that annotations have no effect on the operation of the code.

The fact that I’m writing this article means that I’m not a Spring Boot expert, so it’s definitely possible that I’m missing something here. And maybe this statement is specifically worded to exclude certain types of effects that annotations have. This makes some sense when it comes to our first annotation: @RestController.

The @RestController annotation partially serves to indicate that the class we are defining will be processing network requests using RESTful standards (REST stands for representational state transfer). If you want to learn exactly what comprises those standards, check out this Red Hat article. For our purposes, we just have to know that this configuration will allow us to respond to a GET request that comes to a certain path. If the @RestController annotation is simply an indication that we’ll be coding that logic, it makes sense that it has no effect on the code.

This assertion is challenged, however, by our second annotation. @RequestMapping accepts an argument that can accept several arguments. The default argument we’ve provided is a path, “/”. This is meant to indicate that “if someone makes a GET request to our root path, execute the logic contained in the following method.” That method simply returns a string that says “Good afternoon Medium.”

If I start my application locally as it’s currently written, it will run on localhost:8080. I can visit this URL in my browser to make GET requests. Here’s the result of visiting the root path while my server is running:

One could argue that this isn’t the result of the annotation, but rather a default action. But if I remove the annotation and restart the server, I get a different result:

Without the annotation, it seems that we’re getting an error on this path. And just to confirm that the annotation is indeed directly affecting my application, I can change the path to “afternoon”:

Trust, but verify

Sources

Solutions Engineer