CODEWITHSUNDEEP
resthttp
Yogesh Badke
Yogesh Badke

Reputation: 4597

Correct REST API semantics to check email exists or not

I have an API that looks like GET user/exists/by?email=<email_here>. The objective of the API is to check if the email exists or not.

I am confused over what should be the proper semantics of the API? Currently, I have 2 options.

Option 1: Use HTTP status codes to drive the API.

Option 2:

Upvotes: 2

Views: 1890

Answers (1)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57279

  • Send 204 if the email exists
  • Send 404 if the email doesn't exist

I don't think you are going to find an authoritative answer to your question.

That said, one thing I would encourage you to do is to look at the HTTP responses being sent by your server, and in particular pay attention to the number of bytes of meta data being sent; the status-line, the headers, and so on.

Then consider carefully whether the difference between a small JSON payload and a zero length payload is all that significant.

Furthermore, recall that if a client doesn't want a copy of the representation to be returned, the client can use the method token HEAD rather than GET to request a refreshed copy of the resource meta data.

200 vs 404 is harder. 200 means that the payload is a representation of the requested resource (which is cacheable by default). 404 means that the payload is a representation of an error message (which is cacheable by default).

The HTTP status codes are metadata about the transfer of documents over a network domain. So it is really the wrong mechanism to use to finesse fine grained distinctions in your documents.

For instance, take a look at the cache invalidation specification, and notice please the distinction between the handling of 2xx and 4xx responses to unsafe requests.

As a matter of principle, HTTP data belongs in the headers, your data belongs in the body, and its only when your data is going to be of interest to general purpose HTTP components that we should be lifting copies of your data into the HTTP meta data.

But, as far as I know, not authoritative. This is all very hand wavy, and not easily matched to a specific RFC or advisory.

Upvotes: 2

Related Questions