Specifica API JSON: quando devo restituire un 404 non trovato?

Se l'utente 52 non esiste, restituisce HTTP 404. Restituzione di HTTP 200 è fuorviante.

Pensaci dal punto di vista del cliente. La seguente finestra di dialogo avrebbe senso per te?

Client: please, I want to know something about user 52.
Server: of course (HTTP 200). What do you want to know?
Client: I want to know the basic information about the user.
Server: There is no information whatsoever about this user; I don't even know what are you talking about.

Il caso in cui è possibile utilizzare HTTP 200 con null è quando non si dispone di informazioni su una parte della voce richiesta. Immagina un caso in cui gli utenti hanno una cronologia degli acquisti, a meno che non si siano registrati di recente e non siano ancora stati approvati (e non possono ordinare nulla). Per un utente normale e approvato, la risposta sarà:

HTTP/1.1 200 OK

{
    "id": 51,
    "name": "Laura Norman",
    "purchase-history": [
        { ... },
        ...
    ]
}

Invece, l'utente 52 non ha una cronologia acquisti:

HTTP/1.1 200 OK

{
    "id": 52,
    "name": "David Johnson",
    "purchase-history": null
}

Questo è semanticamente diverso da una sequenza vuota. "purchase-history": [] significa che l'utente ha una cronologia, ma non ha ancora acquistato nulla. Un null ha un significato molto diverso.

Non guardarlo solo dal punto di vista dell'API, ma anche dal punto di vista del cliente.

Se richiedo link come client, ci sono alcune cose che non sono inaspettate: errore totale senza nemmeno ottenere uno stato codice (nessuna rete, https rifiutato se fosse https), stato 401 o 500 (500 è sempre possibile se il server è confuso), ma le due possibilità essenziali sono che l'utente non esiste o che l'utente esiste. E entrambi sarebbero gestiti dal codice cliente in modi molto diversi. In questo modo spero sia per lo stato 200 + l'informazione che voglio, sia per lo stato 404 (non trovato).

È diverso se ho una ricerca in cui è possibile restituire un numero qualsiasi di elementi, inclusi zero, uno o più articoli. In tal caso, mi aspetto che lo stato 200 e una serie di elementi, che potrebbe essere un array vuoto. Lo stato 404 mi aspetterei se l'API non arrivasse mai alla ricerca. Ad esempio, se cerco tutti gli acquisti dell'utente 52 da marzo a luglio, mi aspetto lo stato 404 se l'utente non esiste e 200 se l'utente esiste.

Non so se l'errore ortografico in un commento su usres / 53 è stato intenzionale o meno. Questo dovrebbe dare uno stato 404, o forse 400. In pratica, il client non chiederà quell'URL (una volta che è stato debugato e funziona correttamente). È abbastanza comune che le API restituiscano una risposta insieme allo stato e in tal caso una risposta che indichi chiaramente che "usres" non è affatto valida sarebbe utile.