RESTful API represent the absence of a thing

Question

Imagine an API to identify whether a person has selected their spirit animal. They can only have zero or one spirit animals.

Currently:

/person/{id}/selectedSpiritAnimal

when they have selected an animal returns http 200 and {selectedAnimal:mole}

but when they have no selection it returns http 404.

This makes my spirit animal unhappy as we're representing a valid domain concern - having not yet selected a spirit animal - as an HTTP error.

Plus, as a business - erm Sprit-Animal-Hampers-R-us - we want to know when someone has no selection so we can prompt them.

What's a better response here:

HTTP 200 and {selectedAnimal:null}

or even more explicit

HTTP 200 and {selectedAnimal:null, spiritAnimalSelected: false}

Or is it better to return a 404? Since much like this image has not yet been uploaded when viewing an image online would be a 404. this person has not selected a spirit animal might be a 404

---

This question has been proposed as a duplicate but that question addresses an otherwise valid URL being requested when the application has been configured to not allow the change that URL represents.

Whereas here I'm looking at how one represents a resource where the absence of the resource is meaningful. I.e. it is valid for the client to request the URL and the response is you have successfully requested the resource which represents an absence of a thing.

So this isn't 'business logic' but rather a circumstance where the absence of a thing has meaning (it may be as many of my colleagues are arguing that 404 is still correct) but I'm not sure how to map that to the spec.

---

Very difficult to pick an answer. I've changed my mind multiple times over the conversation here and the one ongoing at work.

The thing that settles it for me here is that the spec says that a 4xx is when the client has erred. In this instance the client has been told to expect a response from the selectedSpiritAnimal url so has not erred.

The consensus amongst my colleagues is that this is a symptom of a bad API design

It would probably be better that we simply request /person/{id} and that returns a set of link relations for the person... then if you aren't given the /selectedSpiritAnimal link (when a person has no selection) but you call it anyway then a 404 makes sense. Or that you implement partial responses and let /person/{id} return a more full document unless the client requests a subset of the data

Answer 1

HTTP 4xx codes are probably not the right choice for this scenario. You state that having zero spirit animals is a valid state, and the API route person/{id}/selectedSpiritAnimal will account for whether person id does or does not have one.

HTTP 4xx responses are reserved for the situation when a client has done something incorrect in the request (see w3's archive of the original spec). But the client is making a valid request, whether or not person id has a spirit animal.

So I lean toward the second solutions using a properly formatted JSON body in the response and an HTTP 2xx code.

Now if you get such a request and it turns out person id does not exist, a 4xx code makes more sense.

Answer 2

Let me introduce you to the Richardson Maturity Model.

Your problem is that you are representing two resources as one, where you should really have two resources which have a relationship indicated by hypermedia. Using hypermedia to describe relationships is the glorious level 3 of Rest.

Your person should live under the URI /person/{id} and the animal should live under /spiritanimal/{id}. The person should indicate that it has spirit animal by using a link to the animal.

Lets imagine a person called Bob, who has id 123 and a Unicorn spirit animal.

GET /person/123

would return;

{
  "name": "Bob",
  "links": [
    {
      "rel": "spiritanimal",
      "uri": "/spiritanimals/789"
    }
  ]
}

Now anybody who reads person 123 will know that they have a spirit animal, and has the URI where they can get more info on it.

GET /spitiranimal/789

might return

{
  "type": "Unicorn"
}

Now lets imagine a person called Fred, who has id 456 and no spirit animal.

GET /person/456

would return;

{
  "name": "Fred",
  "links": [
  ]
}

Now anybody who reads person 456 will know that they have no spirit animal, as there is no link. There is no need to use any HTTP status code to represent the lack of a relationship.

Answer 3

This is the appropriate url for getting spirit animals; therefore, a 404 error is inappropriate. 404 is for representing a technical problem, not a logic problem.

The appropriate solution is to return http 200 and {"selectedAnimal": null}

You should have a seperate webmethod /person/{id}/hasSelectedSpiritAnimal which returns {"isSpiritAnimalSelected": false}. Behind the scenes, it may or may not make the same method calls, just returning false if null, but that is up for it to decide, not the consuming code.

It is better to avoid combining to separate queries into one web method without a compelling reason to do so, even if the queries are closely related.

Answer 4

What your endpoint represents is not just an animal; it's an animal or lack of it. It's a value best represented by an Optional / Maybe / Nullable / etc.

So legitimate values (as in 200 OK) may be:

• {'animal': <some animal>, 'selected': true}
• {'animal': null, 'selected': false}

I could imagine that DELETE method, when applied to the endpoint, can set 'selected' to false again, that is, unset the selected animal.

You can, of course, drop the 'selected' key here, it is only shown for clarity; string vs null is enough for the distinction.

Answer 5

You should use 404.

The 404 (Not Found) status code indicates that the origin server did not find a current representation for the target resource

RFC7231

HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 25 Sep 2017 00:00:00 GMT

"mole"

HTTP/1.1 404 Not Found
Content-Type: text/plain
Date: Mon, 25 Sep 2017 00:00:00 GMT

this person has not selected a spirit animal

Since you are making an programming interface, not a human interface, the 404 text is optional.

I prefer this because I prefer standard protocols as much as possible. HTTP has a way to represent non-existance, and that's what I would use.

EDIT: Suppose you added a feature where users could choose whether to share their spirit animals, and someone didn't share it. Would you return 200 OK null, or 200 OK "Unauthorized? Or would you use the the standard 401 Unauthorized/403 Forbidden? This seems directly analogous to not choosing one in the first place.

---

Alternatively, if you want to used 200 OK + JSON, you should return null.

HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 25 Sep 2017 00:00:00 GMT

"mole"

HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 25 Sep 2017 00:00:00 GMT

null

Keep things clean. Create more wrapping only if necessary.