If you’re learning Java backend development, one of the first things you’ll probably want to build is a REST API.

REST APIs are everywhere.

Web applications use them. Mobile apps use them. Frontend frameworks like React and Angular use them. Even different backend services often communicate with each other through APIs.

The good news is that Java and Spring Boot make building REST APIs surprisingly straightforward.

In this guide, we’ll build a REST API from the ground up and understand the important concepts along the way.

We’ll cover:

• What a REST API is
• How HTTP methods work
• Creating a Spring Boot project
• Creating controllers
• Handling GET, POST, PUT, and DELETE requests
• Working with path variables and query parameters
• Handling JSON
• Using services and repositories
• Connecting a database
• Handling errors
• Validating requests
• Testing your API
• Best practices

Let’s get started.

---

What Is a REST API?

Before writing code, let’s understand what a REST API actually is.

REST stands for Representational State Transfer.

A REST API allows applications to communicate over HTTP using resources and standard HTTP methods.

For example, imagine an application that manages users.

You might have an API like:

GET    /api/users
GET    /api/users/10
POST   /api/users
PUT    /api/users/10
DELETE /api/users/10

Each endpoint represents a resource or operation involving users.

Conceptually:

Client
  ↓
HTTP Request
  ↓
REST API
  ↓
Application Logic
  ↓
Database
  ↓
HTTP Response
  ↓
Client

The client could be a web browser, mobile application, frontend application, or another backend service.

---

What Is an API Endpoint?

An endpoint is a URL through which a client can interact with your API.

For example:

/api/products

could represent a collection of products.

And:

/api/products/25

could represent a specific product.

You can think of it like this:

/api/products
       ↓
All Products


/api/products/25
       ↓
Product with ID 25

---

HTTP Methods You Should Know

REST APIs commonly use several HTTP methods.

Method	Common Purpose
GET	Retrieve data
POST	Create data
PUT	Replace/update a resource
PATCH	Partially update a resource
DELETE	Delete data

Let’s see how these map to a product API.

GET    /api/products       → Get products
GET    /api/products/10    → Get product 10
POST   /api/products       → Create product
PUT    /api/products/10    → Update product 10
DELETE /api/products/10    → Delete product 10

---

Creating a Spring Boot Project

The easiest way to start a Spring Boot project is to use Spring Initializr.

For a basic REST API, you’ll typically need:

Spring Web

If you’re working with a database, you might also add:

Spring Data JPA
Database Driver

For example, a project might use:

Java
Maven
Spring Web
Spring Data JPA
PostgreSQL

Spring Boot then generates the basic project structure for you.

---

Basic Spring Boot Application

Your main application class will look something like this:

@SpringBootApplication
public class Application {

    public static void main(String[] args) {

        SpringApplication.run(
            Application.class,
            args
        );
    }
}

The @SpringBootApplication annotation enables the main Spring Boot configuration.

When you run the application, Spring Boot starts the application context and, for a typical web application, starts the embedded web server.

---

Creating Your First REST Controller

Let’s create a simple controller.

@RestController
@RequestMapping("/api/hello")
public class HelloController {

    @GetMapping
    public String hello() {
        return "Hello from Spring Boot!";
    }
}

Now start your application and make a request:

GET /api/hello

You should receive:

Hello from Spring Boot!

Congratulations — you’ve created your first REST endpoint.

---

Understanding @RestController

This annotation:

@RestController

tells Spring that the class handles HTTP requests and that its methods typically return data directly in the HTTP response body.

For APIs, this is commonly used instead of a traditional MVC controller that returns a view.

---

Understanding @RequestMapping

This annotation:

@RequestMapping("/api/hello")

sets the base path for the controller.

So if the method has:

@GetMapping

the complete endpoint becomes:

GET /api/hello

You can also define the HTTP method directly in the mapping:

@GetMapping("/users")

@PostMapping("/users")

and so on.

---

Building a Simple Product API

Let’s create a small example.

Suppose we have a Product class:

public class Product {

    private Long id;
    private String name;
    private double price;

    public Product() {
    }

    public Product(
        Long id,
        String name,
        double price
    ) {
        this.id = id;
        this.name = name;
        this.price = price;
    }

    // Getters and setters
}

Now we can create a controller.

@RestController
@RequestMapping("/api/products")
public class ProductController {

    @GetMapping
    public List<Product> getProducts() {

        return List.of(
            new Product(1L, "Laptop", 900),
            new Product(2L, "Phone", 600),
            new Product(3L, "Monitor", 350)
        );
    }
}

A request to:

GET /api/products

could return:

[
    {
        "id": 1,
        "name": "Laptop",
        "price": 900
    },
    {
        "id": 2,
        "name": "Phone",
        "price": 600
    },
    {
        "id": 3,
        "name": "Monitor",
        "price": 350
    }
]

Spring Boot handles the conversion from Java objects to JSON for a typical REST application.

---

Creating a GET Endpoint

The @GetMapping annotation is used for GET requests.

@GetMapping
public List<Product> getProducts() {
    return products;
}

You can also retrieve a specific product.

@GetMapping("/{id}")
public Product getProduct(
        @PathVariable Long id
) {
    return findProduct(id);
}

Now:

GET /api/products/10

can retrieve the product with ID 10.

---

What Is @PathVariable?

A path variable extracts a value directly from the URL.

For example:

/api/products/10

Here 10 is part of the URL path.

You can capture it using:

@GetMapping("/{id}")
public Product getProduct(
        @PathVariable Long id
) {
    // ...
}

Conceptually:

/api/products/{id}
              ↓
             10

---

Using Query Parameters

Sometimes you don’t want information in the URL path.

Instead, you can use query parameters.

For example:

GET /api/products?category=laptop

You can access the parameter using @RequestParam.

@GetMapping
public List<Product> getProducts(
        @RequestParam String category
) {
    // ...
}

You can also make parameters optional:

@GetMapping
public List<Product> getProducts(
        @RequestParam(required = false)
        String category
) {
    // ...
}

---

Creating a POST Endpoint

GET is mainly used to retrieve information.

To create a resource, you commonly use POST.

For example:

@PostMapping
public Product createProduct(
        @RequestBody Product product
) {
    return product;
}

The client might send:

{
    "name": "Keyboard",
    "price": 80
}

The @RequestBody annotation tells Spring to read the request body and convert the JSON into a Java object.

---

What Is @RequestBody?

Suppose the client sends:

{
    "name": "Keyboard",
    "price": 80
}

Spring can convert that JSON into:

Product product

using:

@RequestBody Product product

So the flow is:

JSON Request
     ↓
Spring
     ↓
Java Object
     ↓
Controller

This makes handling JSON APIs much easier.

---

Creating a PUT Endpoint

PUT is commonly used when you want to replace or update a resource.

For example:

@PutMapping("/{id}")
public Product updateProduct(
        @PathVariable Long id,
        @RequestBody Product product
) {
    // Update product
    return product;
}

A request could look like:

PUT /api/products/10

with:

{
    "name": "Updated Laptop",
    "price": 1000
}

---

Creating a DELETE Endpoint

To delete a resource, you can use @DeleteMapping.

@DeleteMapping("/{id}")
public void deleteProduct(
        @PathVariable Long id
) {
    // Delete product
}

The request would be:

DELETE /api/products/10

---

A Complete CRUD Controller

Putting the basic operations together:

@RestController
@RequestMapping("/api/products")
public class ProductController {

    @GetMapping
    public List<Product> getProducts() {
        return productService.getProducts();
    }

    @GetMapping("/{id}")
    public Product getProduct(
            @PathVariable Long id
    ) {
        return productService.getProduct(id);
    }

    @PostMapping
    public Product createProduct(
            @RequestBody Product product
    ) {
        return productService.createProduct(product);
    }

    @PutMapping("/{id}")
    public Product updateProduct(
            @PathVariable Long id,
            @RequestBody Product product
    ) {
        return productService.updateProduct(
            id,
            product
        );
    }

    @DeleteMapping("/{id}")
    public void deleteProduct(
            @PathVariable Long id
    ) {
        productService.deleteProduct(id);
    }
}

This gives you the basic CRUD operations:

Create → POST
Read   → GET
Update → PUT
Delete → DELETE

---

Why Use a Service Layer?

You might be wondering:

“Why not put all the logic inside the controller?”

You can for a tiny example, but it’s not a good approach for larger applications.

A cleaner architecture is:

Controller
    ↓
Service
    ↓
Repository
    ↓
Database

The controller handles HTTP requests.

The service handles business logic.

The repository handles data access.

This separation keeps your application easier to maintain.

---

Creating a Service

For example:

@Service
public class ProductService {

    public List<Product> getProducts() {

        // Business logic

        return productRepository.findAll();
    }
}

Then the controller can use the service through constructor injection:

@RestController
@RequestMapping("/api/products")
public class ProductController {

    private final ProductService productService;

    public ProductController(
            ProductService productService
    ) {
        this.productService = productService;
    }
}

Spring automatically provides the ProductService dependency.

---

Connecting a Database

A real API usually needs persistent data.

Instead of keeping products in memory:

List<Product> products;

you can store them in a database.

A common approach is using:

Spring Data JPA

with a relational database such as PostgreSQL or MySQL.

---

Creating an Entity

Your Product class can become a JPA entity:

@Entity
public class Product {

    @Id
    @GeneratedValue
    private Long id;

    private String name;

    private double price;

    // Getters and setters
}

The @Entity annotation tells JPA that the class represents persistent data.

---

Creating a Repository

You can create a repository like this:

public interface ProductRepository
        extends JpaRepository<Product, Long> {
}

Spring Data provides many common database operations automatically.

For example:

productRepository.findAll();

productRepository.findById(id);

productRepository.save(product);

productRepository.deleteById(id);

This means you don’t need to write SQL for every basic CRUD operation.

---

API Request Flow with a Database

Now your application might look like:

Client
  ↓
Controller
  ↓
Service
  ↓
Repository
  ↓
Database

For example:

GET /api/products/10
        ↓
ProductController
        ↓
ProductService
        ↓
ProductRepository
        ↓
Database
        ↓
Product
        ↓
JSON Response

This layered structure is common in Spring Boot applications.

---

Returning Proper HTTP Status Codes

A good REST API shouldn’t return the same status code for every situation.

Some commonly used HTTP status codes are:

Status	Meaning
200	Request successful
201	Resource created
204	Successful request with no response body
400	Bad request
401	Authentication required
403	Forbidden
404	Resource not found
409	Conflict
500	Server error

For example, after successfully creating a resource, you might return:

201 Created

rather than simply:

200 OK

---

Using ResponseEntity

Spring provides ResponseEntity when you need more control over the HTTP response.

For example:

@PostMapping
public ResponseEntity<Product> createProduct(
        @RequestBody Product product
) {

    Product saved =
        productService.createProduct(product);

    return ResponseEntity
            .status(HttpStatus.CREATED)
            .body(saved);
}

This lets you control:

• Status code
• Response body
• Headers

---

Handling 404 Errors

Suppose a client requests:

GET /api/products/999

but product 999 doesn’t exist.

You shouldn’t simply return null.

A better API should return something like:

404 Not Found

One approach is using a custom exception.

public class ProductNotFoundException
        extends RuntimeException {

    public ProductNotFoundException(Long id) {
        super("Product not found: " + id);
    }
}

Then you can handle the exception centrally.

---

Global Exception Handling

Spring provides @RestControllerAdvice for centralized exception handling.

For example:

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(
        ProductNotFoundException.class
    )
    public ResponseEntity<String> handleNotFound(
            ProductNotFoundException exception
    ) {

        return ResponseEntity
                .status(HttpStatus.NOT_FOUND)
                .body(exception.getMessage());
    }
}

Now your controllers don’t need to repeat the same error-handling logic everywhere.

---

Validating API Requests

Your API should validate incoming data.

For example, a product shouldn’t have a negative price.

You can use Bean Validation annotations.

public class ProductRequest {

    @NotBlank
    private String name;

    @Positive
    private double price;
}

Then:

@PostMapping
public Product createProduct(
        @Valid @RequestBody ProductRequest request
) {
    // ...
}

Common validation annotations include:

@NotNull
@NotBlank
@NotEmpty
@Size
@Min
@Max
@Positive
@Email

Validation helps prevent invalid data from entering your application.

---

DTOs: Don’t Always Expose Your Entity

A common beginner mistake is using the database entity directly as the API request and response model.

For small applications this can be acceptable, but larger applications often use DTOs.

DTO stands for:

Data Transfer Object

For example:

public class ProductResponse {

    private Long id;
    private String name;
    private double price;
}

And a separate request object:

public class ProductRequest {

    @NotBlank
    private String name;

    @Positive
    private double price;
}

This gives you more control over what your API accepts and returns.

---

API Versioning

As your API evolves, you may need to introduce changes without breaking existing clients.

One common approach is URL versioning:

/api/v1/products
/api/v2/products

Another approach is using headers.

The important idea is:

Design your API so changes can be introduced without unexpectedly breaking clients.

---

Testing Your REST API

Once your API is running, you need to test it.

Popular tools include:

• Postman
• Insomnia
• curl
• HTTP clients inside IDEs
• Automated tests

For example, using curl:

curl http://localhost:8080/api/products

For a POST request:

curl -X POST \
  http://localhost:8080/api/products \
  -H "Content-Type: application/json" \
  -d '{"name":"Keyboard","price":80}'

Testing helps you verify that endpoints behave correctly.

---

Documenting Your API

As APIs grow, documentation becomes important.

Developers need to know:

• Available endpoints
• HTTP methods
• Request parameters
• Request bodies
• Response formats
• Status codes
• Authentication requirements

Tools based on OpenAPI can help generate interactive API documentation.

A documented API is much easier for frontend developers and other backend services to consume.

---

Securing a REST API

Real-world APIs usually shouldn’t be completely open.

You may need authentication and authorization.

Spring Security can help implement things such as:

• Authentication
• Authorization
• Role-based access
• JWT-based authentication
• OAuth2
• Password security

For example:

Client
  ↓
Login
  ↓
Authentication
  ↓
Access Token
  ↓
API Request
  ↓
Spring Security
  ↓
Controller

Security is a large topic, so it’s worth learning separately once you’re comfortable with REST fundamentals.

---

REST API Best Practices

Here are some useful practices to follow when designing Spring Boot APIs.

Use Meaningful Resource Names

Prefer:

/api/products

over:

/api/getAllProducts

The HTTP method already tells you the action.

---

Use HTTP Methods Correctly

For example:

GET    → Read
POST   → Create
PUT    → Replace/Update
PATCH  → Partial Update
DELETE → Delete

---

Return Appropriate Status Codes

Don’t return 200 OK for every situation.

Use appropriate status codes such as:

201 Created
400 Bad Request
404 Not Found
409 Conflict
500 Internal Server Error

---

Validate Input

Never assume the client will always send valid data.

Validate request bodies and parameters before processing them.

---

Keep Controllers Thin

Avoid putting complicated business logic inside controllers.

A cleaner structure is:

Controller
    ↓
Service
    ↓
Repository

---

Use DTOs When Appropriate

DTOs help keep your API contract separate from your database model.

---

Handle Errors Consistently

Use centralized exception handling so your API returns predictable error responses.

---

A Typical Spring Boot REST API Architecture

A production-style application might look like this:

                    Client
                      ↓
                REST Controller
                      ↓
                 Service Layer
                      ↓
                Repository Layer
                      ↓
                   Database

Alongside this, you may have:

Security
Validation
Exception Handling
Logging
Testing
API Documentation
Configuration

Each part has a specific responsibility.

---

Complete REST API Learning Path

If you’re a beginner, don’t try to learn everything at once.

A good progression is:

Java Basics
     ↓
Spring Boot Basics
     ↓
REST Concepts
     ↓
Controllers
     ↓
GET / POST / PUT / DELETE
     ↓
RequestBody / PathVariable / RequestParam
     ↓
Service Layer
     ↓
Spring Data JPA
     ↓
Database
     ↓
Validation
     ↓
Exception Handling
     ↓
DTOs
     ↓
Security
     ↓
Testing
     ↓
API Documentation

Build a small CRUD project after each major concept.

---

Final Thoughts

Building REST APIs with Java and Spring Boot becomes much easier once you understand the basic building blocks.

At the beginning, focus on these concepts:

• REST
• HTTP methods
• Controllers
• Request and response bodies
• Path variables
• Query parameters
• Services
• Repositories
• Databases
• Validation
• Exception handling
• HTTP status codes

A typical Spring Boot API follows a flow like:

Client
  ↓
Controller
  ↓
Service
  ↓
Repository
  ↓
Database

Once you’re comfortable with this structure, you can start adding more advanced features such as authentication, authorization, caching, API documentation, testing, Docker, and microservices.

The best way to learn REST APIs isn’t just by reading about them.

Build one.

Start with a simple CRUD API, connect it to a database, test every endpoint, handle errors properly, and then gradually add authentication and other production features.

That’s when Spring Boot starts to really make sense.