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?
API stands for Application Programming Interface. In other words, an API is a tool that helps services communicate with each other by the handling of requests. We send an API certain data (a request) and the API handles that by executing certain tasks, sending further requests, or sending a response. They’re so ubiquitous because they allow our product or service communicate with other products and services without having to know how they’re implemented. Without that, the internet as we know it would fail to function, as well as any application that connects to another.
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
The first result when searching “spring boot annotations” in Google is this really helpful list from JavaTpoint. That article begins by stating (emphasis mine):
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
This is far from a conclusion that the JavaTpoint documentation should be changed, but it is a helpful reminder that the initial understanding of a concept isn’t always the correct one. When we learn how something works, we should be open to corrections or assertions that augment our knowledge. If someone told me that annotations didn’t affect the performance of a Spring Boot application, I wouldn’t tell them they were wrong. Instead, I’d ask them if they could help me understand by explaining how @RequestMapping works, starting a conversation that will no doubt improve my knowledge of the concept.
Sources
- What is an API?, Red Hat
- Compilation Units, Oracle
- Spring Boot Annotations, JavaTpoint
- What is a REST API?, Red Hat
- Learn SpringBoot in 10 minutes | SpringBoot REST API Tutorial, blondiebytes