1

Say I am building an API that serves the content of old magazines. The client can request the content of the latest edition prior to a given date, something like:

GET /magazines/<some_magazine_id>?date=2015-03-15

The response includes general data about the magazine, such as its name, country of distribution, the date of creation..., and if my database has content available for an edition prior to the date given, it returns it as well.

What HTTP status code should I use if the client requests data for a date before anything I have available? I might have data in the future, when I expand the content of my database. So this is sort of a temporary failure, but it's unclear how long it may take before it is fixed.

Based on other questions, I feel like:

  • 404 is not right: in some cases, I have no data at all about a magazine, in which case I'd return a 404. But this is different. I would like the user to get the partial data, but with an indication that it's only partial.
  • 4xx are client-side errors. I feel like the client didn't do anything wrong.
  • 206 Partial Content seems indicated when returning a range of the content, but not all of it.
  • 30x I thought about using a 302 or similar, and point to the closest edition available, but again, I am not sure that this is right, because I am now pointing to something semantically different from the question asked.
  • 5xx would be errors, and I think should not contain any data.

My best guess would be something like a 2xx No Details Available (Yet) indicating that the request was "somewhat successful", but I can't find anything that seems correct in the list.

Laurent S
  • 4,106
  • 3
  • 26
  • 50

1 Answers1

1

I would go with a 200 OK. You did find the magazine and you are returning data about it. While your data is not as complete as it might have been, it is a complete response that can be understood. Presumably you are returning an empty array or a nil reference where the edition(s) would have been?

The problem with many of the more specific responses are that they are really intended for something more low-level. You are not returning partial content, you are returning the full content. It is just that the higher-level application data is not as complete as you might have wished (no old edition found). On the REST/HTTP level the response is just fine.

ewramner
  • 5,810
  • 2
  • 17
  • 33
  • This makes a lot of sense. I think I was trying to conflate higher-level application logic with REST. Thank you for clarifying this aspect. – Laurent S Mar 16 '20 at 07:31