Your API Breaks Because Someone Used Caps Lock - DEV Community

It starts with a simple question: what happens when someone types your API endpoint in all caps? API.EXAMPLE.COM instead of api.example.com. Most developers would assume the request should work exactly the same way. After all, DNS doesn't care about casing, browsers don't care, and most networking tools don't care. But surprisingly often, the API breaks.

This isn't theoretical. Rentgen runs a straightforward mutation test that takes an exact request and uppercases only the domain. Nothing else changes. The expected behavior is clear: the same 2xx response as the original request. When it fails, that's not an edge case—that's infrastructure smell.

The worst part about this bug is how invisible it is until it hits production. When an API fails due to case sensitivity, teams typically debug payloads, authentication, headers, and routing logic. They check for malformed requests, verify authentication tokens, examine proxy configurations, and review routing rules. Meanwhile, the root cause is literally sitting in plain sight: someone pressed Caps Lock.

In practice, this test often passes with a clean 200 OK response. That's how it should behave. But when it fails in real systems, the causes are usually predictable and preventable:

• Sloppy reverse proxy rules that perform case-sensitive host matching
• Case-sensitive host header comparisons in application code
• Development configurations that were "temporary" three years ago and never fixed
• Load balancer rules that normalize or don't normalize host headers inconsistently

The technical root cause is almost always somewhere in the stack treating the Host header as raw text rather than as an identifier. The Host header should be normalized before comparison—typically by converting to lowercase—since domain names are case-insensitive by specification.

This issue highlights a broader principle in API design: robustness. Your API should handle reasonable variations in how clients format requests. If your system breaks because of something as trivial as letter casing, it suggests fragility elsewhere in your infrastructure.

The fix is usually straightforward once identified. Normalize the Host header early in your request processing pipeline. Ensure your reverse proxies and load balancers handle domain normalization consistently. Add automated tests that verify case-insensitive behavior. Most importantly, recognize that this isn't about supporting "weird" edge cases—it's about meeting the basic expectations of how HTTP and DNS work.

For teams looking to catch these issues before they reach production, mutation testing tools like Rentgen can automate these kinds of checks. The uppercase domain test is just one example of how simple transformations can reveal hidden assumptions in your infrastructure.

Your API shouldn't break because someone typed in uppercase. It's not a feature request—it's a bug fix for something that should have worked from day one.