A question I’ve always had about 404 and APIs... How do you distinguish between an invalid path (no end point) and a valid path requesting a resource that doesn’t exist?
You don't
Best practices for REST API design (2020)
21–30 of 273 posts
Re: Best practices for REST API design (2020)
#22Re: Best practices for REST API design (2020)
#23> Then if we try to submit the payload with the email value that already exists in users, we’ll get a 400 response status code with a 'User already exists' message to let users know that the user already exists. With that information, the user can correct the action by changing the email to something that doesn’t exist. I was always under the impression that 409 would be the "correct" code here, while you'd use 400 i…
Ironically, your comment is a perfect illustration of one of the problems with REST - its tendency to provoke discussion about things that don't actually matter in practice.
No user cares whether an error response came back with a 400 or a 409 status, or what those codes even mean. It's madness that as a profession we spend so much of our employers' time and money on trivial things that deliver no value whatsoever. Response codes, HTTP verbs and pretty hierarchical URLs are all meaningless. I've lost count of the number of meetings I've been in where there have been pointless, timewasting debates about these things. Should we expose separate /foos and /bars endpoints? Should it be /foos/{foo_id}/bars/{bar_id}? Or maybe both? Do we need a POST, a PUT or a PATCH? Etc, ad nauseam.
I'm generally cautious when it comes to embracing new technologies, but I've wholeheartedly embraced GraphQL simply because it has removed countless hours of unproductive bikeshedding from my professional life.
Re: Best practices for REST API design (2020)
#24I'd recommend against using `v1` in the path and prefer content negotiation:
GET /resource/1
Accept-Version: ~1.0.2
...
The pain of REST is that there's very little in terms of "correct" as we don't have a formal specification of the semantics. If you end up using /v1 it's not any more or less REST-ful.
Re: Best practices for REST API design (2020)
#25Just for a point of reference here is Google’s take on the exact same topic. It has a bit more of a gRPC background but still is very REST friendly by default.
https://cloud.google.com/apis/design/resources
Also as one of the most common pushbacks people have with gRPC is that everyone generally expects JSON still in 2021 especially in the browser. Not sure if this is super well known or not but gRPC integrates well with things like envoy which allow you to write a single gRPC API and have it serve and respond to both native gRPC and standard REST / JSON calls.
Re: Best practices for REST API design (2020)
#26A question I’ve always had about 404 and APIs... How do you distinguish between an invalid path (no end point) and a valid path requesting a resource that doesn’t exist?
If doesn't exist means it has been removed: 410 Gone, if doesn't exist means not yet created: 404 Not Found.
I can't think for other types of not existing, or why you'd need to differentiate between them.
Re: Best practices for REST API design (2020)
#27A question I’ve always had about 404 and APIs... How do you distinguish between an invalid path (no end point) and a valid path requesting a resource that doesn’t exist?
From a client application perspective, would you want to handle the cases differently?
Re: Best practices for REST API design (2020)
#28A question I’ve always had about 404 and APIs... How do you distinguish between an invalid path (no end point) and a valid path requesting a resource that doesn’t exist?
This is where error response messages should come into play. Returning a JSON object with a "message" attribute containing "No such route/path" vs "Object not found" depending on the context of the 404 makes it immediately clear where the issue is.
Re: Best practices for REST API design (2020)
#29All these "best practices" are exactly why I embraced GraphQL quickly and flushed "REST" down the toilets for big projects (http+json is fine for small ones, since no lib overhead). GraphQL is unashamedly the new SOAP. I.e. we have a spec, not a series of "best practices" thus endless architectural debates where people are shamed for 'doing it the wrong way' online. - Accept and respond with JSON: No, why? what if I…
Never understood the hype around GraphQL. You want to know how to halve your performance and responses/s on your service? add graphql. All things that GraphQL claims to do can be implemented in RESTful services easily. If you want specificity in your query fetching, just add query params or put them in the request body If you want schema validations, there are many libraries that help you with that. And if you want d…
> All things that GraphQL claims to do can be implemented in RESTful services easily.
How do you easily write an endpoint that can either return a comment, a comment with its children, a comment with its corresponding story, with a strongly typed schema (ie. no optional children or story whatever the query is)?
Re: Best practices for REST API design (2020)
#30A question I’ve always had about 404 and APIs... How do you distinguish between an invalid path (no end point) and a valid path requesting a resource that doesn’t exist?
You can distinguish between them in your response body. A simple error response body for a JSON-oriented REST API is often something like a JSON object with a human-readable error message, and a unique code for that type of error. i.e. {“message”:”No such route”, “code”:”ad01fd04-8e9e-4326-9576-3d479fa20637”}