The Bug I Found When Special Characters Broke My API

Today, I worked on a simple Spring Boot API, but it taught me an important lesson about handling user input properly.

I created an endpoint to add a scope of work to a project:

@PostMapping("/addScopeOfWork/{projectId}/{scopeOfWork}")
 public ManageProject addScopeOfWork(@PathVariable Long projectId, @RequestBody Map<String, String> data)
 {
 String scopeOfWork = data.get("scopeOfWork");
 return service.addScopeOfWork(projectId, scopeOfWork);
 }

At first , everything is fine.

When I tested the API with normal text, it worked perfectly.

But when I passed special characters like:

&
/
?
%

The API started crashing.

Why Did This Happen?
/addScopeOfWork/{projectId}/{scopeOfWork}

Here, scopeOfWork is part of the URL (path variable).

Special characters are not safe inside URLs unless they are encoded.

For example:

/ is treated as a path separator
? starts query parameters
& separates parameters

So the server misunderstand the input and breaks the request

Instead of passing scopeOfWork in the URL, I moved it to the request body.

@PostMapping("/addScopeOfWork/{projectId}") 
public ManageProject addScopeOfWork(@PathVariable Long projectId, @RequestBody Map<String, String> data) 
{ 
String scopeOfWork = data.get("scopeOfWork"); 
return service.addScopeOfWork(projectId, scopeOfWork); 
}

Now the request looks like:

{
"scopeOfWork": "Fix login & payment issues / urgent"
}

---This works perfectly because:

What I Learned

• Never pass user input with special characters in URL path variables

• Always use request body for text data

• Understand how HTTP URLs work before designing APIs

Final Thought

Sometimes small bugs teach the biggest lessons.

This issue helped me understand how important proper API design is — especially when handling real-world data.

Just because it works with simple input doesn’t mean it works in real-world scenarios.