10

Let's assume we have an Entity

{
    "id": 1
    "inProgress": true,
}

We have endpoints:

  • /api/v1/entities/ for fetching all entities,
  • /api/v1/entities/1 for fetching entity with id = 1
  • /api/v1/entities/in-progress for fetching entity which is in progress. Note that there can be only one entity in progress.

Now, we can have 2 situations for /api/v1/entities/in-progress:

  1. there is an entity in progress
  2. there is no entity in progress right now

Which status code should be returned for 2-nd case ?

404 - Not found

Looks ok, because there is no entity. Also, for 404 HTTP says The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.

200

Looks also ok, because request succeeded, but why should we return a null result?

204

Request succeeded but there is no result. Which also seems to be ok.

Which status code would you use and why?

Maxian Nicu
  • 217
  • 2
  • 3
  • 2
    See also [Http Status Code When Downstream Validation Fails](https://softwareengineering.stackexchange.com/questions/399962) – Robert Harvey Nov 01 '19 at 14:35
  • Isn't it pretty obvious that the resource _is found_, and _there is no result_? So 404 surely isn't applicable, whereas 204 is prettty much 100% on target, isn't it? Returning 404 would mean there is no such thing as `/api/.../in-progress` which isn't the case. – Damon Nov 01 '19 at 18:50

1 Answers1

26

HTTP status codes in the 4xx range signify client errors. So I don't think that using a 404 is applicable here. If you were to consider it a client error, then you also say that the client must have knowledge about the state of the server, and that indicates a highly coupled design.

As JimmyJames nicely put it in his comments,

404 means "I don't know what you are referring to". This is very different from, "I know exactly what you are asking but there's no data."

But you say that only one entity can be in progress at any point in time. This sounds like a business rule, and if decide to only return one object in the URL, then your interface reflects the business rules.

I would suggest you consider returning an array from the in-progress url. Then incidentally, you can get an array with either zero or one result.

Perhaps even change this to be a query, so you ask for /api/v1/entities?in-progress=true

Pete
  • 8,916
  • 3
  • 41
  • 53
  • 2
    That's the correct answer. The server has a response it can report, and it is the correct response, therefore it should be status 200. An array is very practical to report 0, 1 or more items in a response. And the client only has to check for status 200 (I've got a correct response), or anything else (something went wrong). – gnasher729 Nov 01 '19 at 11:14
  • 13
    In a nutshell, 404 means "I don't know what you are referring to". This is very different from, "I know exactly what you are asking but there's no data." The only exception here is that the RFC says you can use 404 as a substitute for 403 forbidden to avoid confirming the existence of the URI to an unauthorized user. – JimmyJames Nov 01 '19 at 15:51
  • @JimmyJames Well put, I took the liberty of adding that to the answer – Pete Nov 04 '19 at 08:44