Non sembra esserci uno standard.
La risposta StackOverflow si inclina verso 410 ANDATO, ma penso che 301 SPOSTATO PERMANENTAMENTE sia più appropriato.
Per fare la scelta corretta, dobbiamo esaminare il tuo caso specifico. Se il tuo obiettivo è far fallire tutte le chiamate a API v1 senza intraprendere ulteriori azioni, 410 GONE funziona per questo. Se desideri una certa continuità, ad esempio il reindirizzamento del client a una versione più recente dell'API in cui la chiamata può avere esito positivo, 3XX funziona, ma quale scegli? Penso che se stai cercando di chiudere l'API v1, 301 SPOSTATO PERMANENTAMENTE aiuta a indicare che meglio di 303 VEDI ALTRO perché 301 suggerisce che tutte le richieste future dovrebbero essere fatte al nuovo url mentre 303 non indica se questa situazione è o meno permanente.
Consiglierei di progettare l'API in modo tale che ciascuna versione rimanga compatibile con le versioni precedenti, in modo che 301 SPOSTATO PERMANENTEMENTE mantenga in modo trasparente la tua API attiva e aggiornata ogni volta che aggiungi nuovi endpoint per nuove versioni dell'API. Penso che sia quello che stai cercando di fare comunque.
Codici di stato HTTP
Il codice di stato HTTP 302 era originariamente troppo ampio e quindi è stato implementato / utilizzato in modo errato, quindi sono stati fatti 303 e 307 per distinguere tra il caso di doppio uso di 302. Alcune API usano 303 per altri scopi.
301 SPOSTATO PERMANENTAMENTE - Il codice di stato 301 (Spostato in modo permanente) indica che alla risorsa di destinazione è stato assegnato un nuovo URI permanente e qualsiasi riferimento futuro a questa risorsa dovrebbe utilizzare uno degli URI allegati.
302 TROVATO - Il codice di stato 302 (Trovato) indica che la risorsa di destinazione risiede temporaneamente con un URI diverso. Poiché il reindirizzamento potrebbe essere modificato in determinate occasioni, il client dovrebbe continuare a utilizzare l'URI della richiesta effettiva per richieste future.
303 VEDI ALTRO - Una risposta 303 a una richiesta GET indica che il server di origine non ha una rappresentazione della risorsa di destinazione che può essere trasferita dal server su HTTP. Tuttavia, il valore del campo Posizione si riferisce a una risorsa che è descrittiva della risorsa di destinazione, in modo tale che una richiesta di recupero su quell'altra risorsa possa comportare una rappresentazione utile ai destinatari senza implicare che rappresenti la risorsa di destinazione originale.
410 GONE - Il codice di stato 410 (Gone) indica che l'accesso alla risorsa di destinazione non è più disponibile sul server di origine e che questa condizione è probabile che sia permanente. Se il server di origine non è a conoscenza o non è in grado di determinare se la condizione è permanente o meno, è necessario utilizzare il codice di stato 404 (Non trovato).
Come gestiscono le API esistenti?
Forse puoi prendere una pagina dall'API di YouTube di Google :
Quando una richiesta API non riesce, YouTube restituirà un codice di risposta HTTP 4xx o 5xx che identifica genericamente l'errore, nonché una risposta XML che fornisce informazioni più specifiche sugli errori che hanno causato l'errore. Per ogni errore, la risposta XML include un elemento di dominio, un elemento di codice e possibilmente un elemento di posizione.
Ulteriori letture: