In case we have a search GET REST API endpoint that returns one or zero results for the currently logged in customer, I am wondering what the correct response status code would be, for instance:
api/subscriptions?productId=1
According to the specifications, the customer can either have ONE subscription, or be WITHOUT a subscription for the product.
As far as I understand, and according to the convention, this should be a 200 result, no matter if the result exists or not (the same logic as for a search endpoint that returns a list of objects). I believe it would be incorrect to return 404 here, as this result is only a resource that MIGHT exist?
I understand that this kind of query might even seem as unconventional, as it's purpose is not only to get the subscription, but also to check if it even exists.
I had the idea to wrap the response model in an object result, with the status code 200:
public class ActiveSubscriptionModel
{
public bool HasActiveSubscription { get; set; }
public SubscriptionModel Subscription { get; set; }
}
TL;DR: 200 is the correct status code to use
As far as I understand, and according to the convention, this should be a 200 result, no matter if the result exists or not (the same logic as for a search endpoint that returns a list of objects).
Not according to convention, but rather according to specification -- 200 is the status code that means that the payload of the HTTP response is a representation of the requested resource.
"You asked me for a representation of the web page identified by /api/subscriptions?productId=1 and that is what I am sending back to you." -- 200.
Notice that the status code (which is metadata of the transfer of documents over a network domain) has nothing at all to do with the semantics of the document in your domain.
204 No Content might be appropriate. Status codes can be somewhat subjective.
Not a great alternative. 204 announces that the payload of the response is zero bytes long and implies that the user agent should not traverse away from the current view.
Compare what we "should" expect of a web browser: a 200 response with a zero length body will traverse to a view of the "empty" web page; a 204 response will leave us looking at the previous view (probably confusing the human being looking at the web page).
Where 204 shines is the scenario where we are in an HTTP compliant editor, making local changes to a resource and sharing them with the server. We hit the save button on our editor, the representation is PUT to the server, the server accepts it as is, and we get to continue editing without refreshing the page.
(You'll see that 205 Reset is similar -- appropriate for when we are doing data entry with web forms).
Part of the trick to choosing appropriate status codes is to remember that the server does not control the client - we're not necessarily sending responses to java script code that we control. So we want to make sure that we are sending messages that everyone will understand the same way.