CODEWITHSUNDEEP
resthttphttp-status-code-404http-status-codes
Mateus Felipe
Mateus Felipe

Reputation: 1171

When route was not implemented on server, should it return 404 or 501?

I always returned 404 when some route has not been implemented and no resource exists. For example, if I have a API that returns people at /api/people, if I try to get a object on /api/animals, I'm going to return 404.

A cowork of mine said 404 is only for not found resources, like if I try to get /api/people/100 but there's no people with ID 100. For the /api/animals he would return 501.

For me, the meaning for 501 is when I have a route that won't support one of the methods, like if I can get /api/people/3 but can't delete it.

I decided to look at the specification:

The 404 (Not Found) status code indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists. A 404 status code does not indicate whether this lack of representation is temporary or permanent; the 410 (Gone) status code is preferred over 404 if the origin server knows, presumably through some configurable means, that the condition is likely to be permanent.

The 501 (Not Implemented) status code indicates that the server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource.

For me it seems the specification is a little ambiguous. At the same time it's arguable that /api/animals has not been found by the origin server (404), it's also true that the origin server did not implement the method to fullfill the request (501).

In this case, what is the most proper status code to return?

Upvotes: 1

Views: 2160

Answers (1)

codebrane
codebrane

Reputation: 4620

If you went into a bookshop and asked the person behind the counter to get "The best 100 cakes" from the shelf and the book wasn't in stock, they would return and politely say "I'm sorry I can't find that book". Automate that in a book finding system and it would return 404.

The manager of the bookshop wouldn't appear, instead of the person looking for your book and tell you "I'm afraid we don't support looking for that particular book as our staff can only look for books we have" (501).

If you went into a bookshop and asked the person behind the counter to get you a lawnmower they would politely reply "I'm sorry I don't know how to do that". That would be a 501. If you asked the person in the bookshop to get rid of a book that you'd just seen on the shelf, that would be a 501 too.

A 404 is, "ok, I know how to get that but it isn't there". A 501 is a "WTF! What do you think this place is?".

Whether the 404 is permanent depends on what is answering the question. If it's a REST API, it could return JSON status saying something like the book is out of stock but is on order, with a likely due date.

The real reason it's a 501 when trying to get the book person to chuck out a book they have on a shelf is, if they just said 404, you'd just say, "there it is there!". They'd need to state the real reason they couldn't do that. They have no business policy that allows them to chuck out random books without buying them.

So, technically, the apparatus is there, they can walk up to the book, grab it but stop with a 501 as the policy hasn't been implemented.

"ok, I know how to turn a REST url into functionality, that's how I know what functionality you want, but hey, we only deal with people here, 501".

Upvotes: 4

Related Questions