Hey, Dev.to community! 👋

Welcome to a beginner-friendly guide to Building REST APIs in Java. Whether you’re just getting started or want to solidify your understanding, this article will walk you through the basics, providing easy-to-follow explanations and practical examples.

What is a REST API?

REST (Representational State Transfer) APIs are a popular way for applications to communicate over HTTP. They allow different software components to interact with each other, sending requests and receiving responses—like asking for data or submitting information.

Why Java?

Java is a robust, object-oriented programming language widely used in enterprise applications. It has excellent support for building scalable and secure REST APIs using frameworks like Spring Boot.

Getting Started: Tools You Need

Before diving into code, let’s make sure you have the right tools:

Java Development Kit (JDK): Ensure you have JDK installed.
IDE: You can use IntelliJ IDEA, Eclipse, or VS Code.
Maven or Gradle: For dependency management.
Spring Boot: A Java framework that simplifies creating web applications, including RESTful services.

Step 1: Setting Up Your Project

You can create a new Spring Boot project using the Spring Initializr, or you can use your IDE’s integrated project creation tools.

Once the project is set up, add the necessary dependencies in your pom.xml (if using Maven):

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

This brings in everything needed to build RESTful APIs.

Step 2: Create a Simple REST Controller

Let’s jump straight into creating our first REST endpoint. In Spring Boot, we use the @RestController annotation to mark a class as a controller for REST APIs. Here's how it looks:

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @GetMapping("/hello")
    public String sayHello() {
        return "Hello, Dev.to!";
    }
}

In this example:

@RestController makes the class a REST API controller.
@GetMapping("/hello") binds HTTP GET requests to the /hello endpoint.
The sayHello() method returns a simple "Hello, Dev.to!" message as the response.

Step 3: Run the Application

To run your Spring Boot application, navigate to the project root and execute:

mvn spring-boot:run

Now, open your browser and navigate to http://localhost:8080/hello. You should see the message, "Hello, Dev.to!"

Step 4: Adding More Endpoints

Let’s add an endpoint that returns a list of users. First, create a User class:

public class User {
    private String name;
    private String email;

    public User(String name, String email) {
        this.name = name;
        this.email = email;
    }

    // Getters and Setters
}

Then, modify the controller to return a list of users:

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.Arrays;
import java.util.List;

@RestController
public class UserController {

    @GetMapping("/users")
    public List<User> getUsers() {
        return Arrays.asList(
            new User("Alice", "alice@example.com"),
            new User("Bob", "bob@example.com")
        );
    }
}

Step 5: Handling POST Requests

To handle POST requests, we use @PostMapping. Here’s an example where we accept user data via POST and return the created user:

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {

    @PostMapping("/users")
    public User createUser(@RequestBody User user) {
        // Normally, you'd save the user to a database here
        return user;
    }
}

With this, you can send a POST request with a JSON body to /users, and it will return the created user.

Step 6: Testing with Postman or curl

To test the POST endpoint, you can use Postman or curl:

curl -X POST http://localhost:8080/users -H "Content-Type: application/json" -d '{"name":"Charlie","email":"charlie@example.com"}'

This will return the JSON response with the created user.

What's Next?

From here, you can explore:

Adding validation: Validate incoming data with annotations like @Valid and @NotNull.
Connecting to a database: Use JPA to store data in a relational database.
Error handling: Customize your API’s error responses using @ControllerAdvice.

Let’s Chat! 💬

I’d love to hear from you! Feel free to ask questions, share feedback, or even showcase what you’ve built in the comments section. Also, don’t forget to share this article with anyone who might find it useful!

Thanks for reading, and happy coding! 🎉

Building REST APIs in Java: Are you a beginner to Java?