Understanding RESTful APIs and Fixing Common Mistakes

1. Introduction

This document covers key concepts of RESTful APIs, the mistakes made in API design, why they were problematic, and how they were fixed.

2. What is a RESTful API?

A RESTful API (Representational State Transfer API) is an architectural style for designing web services that follow a structured and predictable way of interacting with resources over HTTP.

Key Principles of RESTful APIs

Why Should APIs Be RESTful?

✅ Scalability – Stateless APIs handle more concurrent requests.
✅ Predictability – Standard HTTP methods make the API easy to understand.
✅ Maintainability – Clean, resource-based URIs make debugging easier.
✅ Interoperability – Any system can use RESTful APIs, regardless of technology.
✅ Faster Development – Consistency speeds up frontend-backend integration.

3. The First Mistake: Non-RESTful URI Design

Old (Incorrect) Code

URI uri = URI.create(ServletUriComponentsBuilder.fromCurrentContextPath().path("/auth/register").toUriString());
return ResponseEntity.created(uri).body(authService.register(request));

What’s Wrong?

🚨 Issue:

• The Location header in the 201 Created response points to the registration endpoint (/auth/register) instead of the newly created user resource.

• The client has no way to directly access the created user.

• Breaks REST principles by not linking resources properly.

Incorrect Response Header

POST /register
Location: http://192.168.1.112:8010/auth/register

🚨 Problem: The Location should point to the newly created user (/users/{id}), not the registration endpoint.

Updated (Correct) Code

URI uri = URI.create(ServletUriComponentsBuilder.fromCurrentContextPath()
                      .path("/users/{id}")
                      .buildAndExpand(response.getUserId()) // Replacing {id} with the actual user ID
                      .toUriString());
return ResponseEntity.created(uri).body(response);

✅ Fixes:

• The Location header now correctly points to the created user (/users/{id}).

• The client can fetch the user directly using GET /users/{id}.

• The API now properly links resources instead of endpoints.

Correct Response Header

POST /register
Location: http://192.168.1.112:8010/users/8311471e-3845-49e2-90b9-826f338efc74

✅ Now, the client knows where to find the new user.

4. The Second Mistake: Returning an Inaccessible Microservice URL

Problem: Wrong Location Header with Internal IP

Even after fixing the resource-based URL, another mistake was found: the Location header returned an internal microservice IP instead of the API Gateway URL.

Incorrect Response (Not Accessible by Client)

HTTP/1.1 201 Created
Location: http://192.168.1.112:8010/users/8311471e-3845-49e2-90b9-826f338efc74

🚨 Issue:

• 192.168.1.112:8010 is an internal microservice IP, not accessible externally.

• The client can’t use this address, as the microservices are only accessible via an API Gateway.

• The correct Location should point to the API Gateway, not the microservice.

Correct Fix: Return the API Gateway URL

String gatewayBaseUrl = "https://api.yourdomain.com"; // Replace with actual gateway URL

URI uri = URI.create(gatewayBaseUrl + "/users/" + response.getUserId());

return ResponseEntity.created(uri).body(response);

✅ Fixes:

• Now the Location header points to the API Gateway (api.yourdomain.com) instead of an internal IP.

• The client can actually access the created resource.

• Microservices remain hidden and secured.

Correct Response Header (Client-Accessible)

HTTP/1.1 201 Created
Location: https://api.yourdomain.com/users/8311471e-3845-49e2-90b9-826f338efc74

✅ Now the client can access the resource through the API Gateway.

5. The Third Mistake: Action-Based Login Instead of Token-Based Authentication

Problem: Using POST /doLogin Instead of POST /auth/tokens

🚨 Issue:

• Login was handled as an action (POST /doLogin) instead of treating authentication as a resource.

• This breaks RESTful principles because authentication should be a resource (auth/tokens), not an action.

Correct Fix: Token-Based Authentication

POST /auth/tokens
Content-Type: application/json

{
  "username": "john_doe",
  "password": "securePassword"
}

✅ The server creates an authentication token and returns it:

HTTP/1.1 201 Created
Location: https://api.yourdomain.com/auth/tokens/abcd1234xyz

{
  "token": "abcd1234xyz",
  "expires_in": 3600
}

• Clients use this token to access secured endpoints:

GET /users/123
Authorization: Bearer abcd1234xyz

✅ This follows stateless authentication and is fully RESTful.

6. Final Takeaways

✅ A microservices-based system must ensure all returned URIs are API Gateway addresses, not internal service addresses.
✅ URIs should be resource-based (/users/{id}) rather than action-based (/doLogin).
✅ Authentication should be token-based (POST /auth/tokens and DELETE /auth/tokens/{id} for logout).

🔥 By following these principles, your API remains RESTful, scalable, and predictable! 🚀