REST API with Spring MVC

A web application always ends up with clients that aren't browsers: a mobile app, a React dashboard, a nightly import script, a partner syncing their catalog. None of these clients wants HTML. They want data, and a reliable way to know whether the operation succeeded.

The instinct is to return JSON from your existing controllers and call it done. That's where poorly designed APIs are born, and the symptom is always the same: everything returns 200. A missing resource returns 200 with a null body. A failed validation returns 200 with an "error" field in the JSON. An exception returns 200 with an empty body. The client can no longer decide anything automatically; it has to inspect the content to guess what happened, and every client guesses differently.

The HTTP status code isn't decoration: it's the only channel that every client, every HTTP library, and every network intermediary understands without a prior convention. A cache handles a 404 correctly, a 429 triggers a retry in a well-written client, and a 201 with a Location header tells you where the created resource lives. Returning 200 everywhere means refusing to use a protocol you're already paying for.