A nuanced opinion on validating URL request parameters

I probably spend more time than I should thinking about which error code to return from various scenarios in my Laravel app.

Recently, Aaron and I were discussing this in the context of a URL path parameter that is incorrect.

For example, let's say you have a URL like PUT /api/v1/products/{product_id} where the product_id is a UUID.

If a user sends in a request with a product_id that does not exist, it's pretty obvious we should return a 404 HTTP status code. But what if they send in a product_id that is not a UUID? It's missing a few characters, or they pass in an integer instead?

At first, I was thinking this should be a 422, which is used by Laravel for validation failures. My thought was that someone building an API integration would appreciate a more specific, and therefore more helpful, error code.

But Aaron talked some sense into me and convinced me it should still be a 404. Why? Well the path parameter is part of the URL, the route into our application. If someone requests a route that doesn't exist, it should be a 404. Trying to be more helpful would actually lead to a less consistent API.

On the other hand, if a query string parameter should be a UUID, and they pass an integer, then we agree a 422 makes sense. It's not part of the routing logic. It's data sent along with the request, just like a form body, which Laravel would validate and return a 422 if there's a failure.

Consistency is good, and having a reason for why you're doing something is even better.

Here to help,

Joel

P.S. We put the same high level of thought into our deep dive on Laravel validation.