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.
Top comments (1)
Nothing humbles a backend dev faster than a perfectly working API… until someone types “Fix login & payment issues / urgent” 😭
We all start with “just pass it in the URL”
and end up learning HTTP the hard way
That moment when:
works → works → works → suddenly everything breaks
Special characters really said:
“nice API you got there… would be a shame if I turned it into 5 different routes”
Good catch moving it to request body
this is one of those bugs you only make once… and never forget again