Per il tuo caso, credo che la restituzione
{ "status" : "off" }
Con un codice di stato 200 è "corretto".
In pratica, non importa molto.
Quando Fielding pubblicò il suo famoso rant on hypertext , chiamò un particolare errore in questo modo:
Failure here implies that out-of-band information is driving interaction instead of hypertext.
Out-of-band in questo caso significa che l'informazione non può essere dedotta dal contenuto della risposta e dalla definizione del tipo di quel contenuto.
Nel tuo esempio, sembra che tu stia cercando di comunicare lo stato dell'irrigatore in modo fuori banda; "quando ottieni un 404, significa che lo sprinkler è spento" è - dal punto di vista di REST - un cheat.
Il modo in banda per inviare tali informazioni è inviando una rappresentazione dello stato dell'irrigatore. Ora, in realtà non c'è nulla che ti impedisca di inviare quella rappresentazione insieme a un 404 - RFC-7231 incoraggia i server a includere una spiegazione della condizione di errore, quindi questo va bene, ma la semantica è sbagliata: "Non sono riuscito a trovare la rappresentazione corrente della risorsa, e anche qui è la rappresentazione che Non ho trovato. "
L'esempio di API Gist è leggermente diverso da cosa hai proposto; dovresti assicurarti di esserne a conoscenza.
In primo luogo, si noti che l'URI di Gist identifica la stella , non la sostanza . In altre parole, considera questa stella come un'entità con un proprio ciclo di vita, piuttosto che come una semplice proprietà. GET / gists /: id / star restituisce la rappresentazione corrente della stella; quando la stella non esiste, non c'è una rappresentazione corrente da trovare e 404 NOT FOUND è appropriata.
Nel tuo esempio, lo sprinkler esiste sempre e ha una proprietà con valori on / off. Affermare che lo sprinkler non è stato trovato perché la proprietà ha il valore sbagliato non corrisponde realmente alla semantica.
Ciò che corrisponderebbe alla semantica sarebbe identificare come risorsa il flusso dell'acqua attraverso l'irrigatore. Una risposta 404 a GET / api / sprinkler / flusso ha perfettamente senso, semanticamente, quando lo sprinkler è spento e il flusso non esiste.
Si noti che questa è solo una questione di progettazione di URI / API - quanto bene l'ortografia di uri comunica ciò che sta accadendo ai lettori umani. Al computer non importa: sta solo seguendo un link. REST non si preoccupa, a patto che l'URI sia fornito dal server, piuttosto che assunto dal cliente. Mettendolo in un altro modo, l'ortografia dell'URI è analoga all'ortografia di un nome di variabile. Quindi se si volesse affermare che / api / sprinkler è l'identificatore per l'entità dell'acqua fluente, la semantica 200/404 andrebbe bene; potresti perdere punti nella revisione del codice per non essere conforme agli standard di denominazione.
Tuttavia, c'è il secondo punto, ovvero che l'API Gist è di fronte al libro dei record per gli elenchi e le stelle. Quando la descrizione della stella viene rimossa dal database gist, la stella è davvero sparita. D'altra parte, "sprinkler" suona come una cosa sul prato fuori nel mondo reale, che trasmette una sorta di segnale che stai riflettendo attraverso la tua API. In tal caso, 404 per indicare off non sembra affatto adatto - il segnale esiste, e lo stai ricevendo, ma ti sta solo dicendo che al momento non scorre acqua.
Le parole di Jim Webber su DDD e REST solleva quello che penso sia un punto importante
The web is not your domain, it's a document management system. All the HTTP verbs apply to the document management domain.
Lo farei ulteriormente e suggerisco che i codici di stato appartengono anche al dominio di gestione dei documenti. In altre parole, 404 dovrebbe significare "Non riesco a trovare il documento che hai richiesto", non "Ho trovato il documento che desideri, e ti sto dicendo che non posso farlo perché tu sappia cosa c'è dentro. "
Tutto ciò detto, 200/404 funzionerà, perché i vincoli con le informazioni fuori banda non si applicano alla tua situazione (la tua API non ha bisogno di ridimensionare le dimensioni del web, non ha bisogno per essere fattibile fino a quando il web, non stai cercando di definire una serie di tipi di media standardizzati per catturare tutte le informazioni in banda, ecc.)