Il nostro servizio è in 5 città al momento. Se qualcuno prova a chiamare la nostra API di servizio da qualsiasi altra città, vogliamo lanciare questo errore Service not available in your area .
La domanda è, quale sarebbe il codice http appropriato per questo errore?
o qualcos'altro?
Qualsiasi codice di errore HTTP sarebbe inappropriato. Non vi è alcun errore o problema di alcun tipo da una prospettiva HTTP, quindi dovrebbe essere qualcosa nella gamma 200. Informi cortesemente alcuni dei tuoi utenti che non saranno riparati inviando un documento che li informa. E tutto va bene.
L'utente non sarà in grado di utilizzare la tua applicazione . Questa è una decisione consapevole presa dalla tua logica aziendale, non una disavventura. A livello HTTP tutto è eccezionale.
Modifica
Sembra che quello che stiamo guardando qui sia uno scontro tra vecchia scuola e nuova scuola. Quando è stato progettato HTTP, non c'erano servizi Web, mancavano SOAP, JSON, no principi REST. Come protocollo sopra TCP questo era già considerato (vicino a) livello di applicazione e sono stati definiti molti codici di stato di alto livello. Quando il web ha iniziato ad essere utilizzato per servizi più ricchi e di alto livello e un mezzo comune per trasportare "buste" era richiesto, i progettisti hanno fatto un hi-jack HTTP piuttosto che definire un protocollo più nuovo e più pulito, solo perché HTTP era onnipresente.
Quindi, in un moderno contesto di servizi Web, l'HTTP è davvero poco più di uno stupido livello di trasporto e la maggior parte dei suoi codici può essere considerata non applicabile o obsoleta. Ne prendi uno solo perché si avvicina al tuo stato di applicazione e si trova in quella lista che una volta significava che qualcosa poteva sembrare innocuo, ma penso che manderebbe un messaggio sbagliato. Non vuoi che HTTP riproduca quel ruolo di regolazione in un contesto di servizio web.
% errori di5xx sono errori del server - qualcosa è andato storto sul server. In particolare, un 503 indica che:
the server is currently unable to handle the request due to a temporary overload or scheduled maintenance
% errori di4xx sono errori del client - il client sta facendo una richiesta che il server non è in grado o non vuole soddisfare. In particolare, un 403 indica che
the server understood the request but refuses to authorize it. A server that wishes to make public why the request has been forbidden can describe that reason in the response payload (if any). [..] However, a request might be forbidden for reasons unrelated to the credentials.
Direi che 503 è chiaramente errato, perché questo non è un problema temporaneo - non si supportano le richieste in quell'area, punto. L'argomento potrebbe essere fatto che alla fine speri di supportare l'area, ma l'intento del codice è quello di includere un'intestazione che indica quando il client può riprovare. "In 6 mesi" non aderisce all'intento.
403 è una scelta migliore perché il tuo servizio vieta semplicemente le richieste da determinate impostazioni locali.
Nessuno di questi.
Se la tua API è ben progettata, l'URL include il nome della città, ad es.
http://example.com/API/Vienna/HailRide
o
http://example.com/API/HailRide?city=Vienna
poiché la geolocalizzazione IP non è affidabile, i tuoi utenti potrebbero utilizzare VPN, i tuoi utenti potrebbero volere un passaggio per qualcun altro, ecc. Suggerire una città in base alla posizione dell'utente è il client API responsabilità. Di solito, il client dispone di risorse molto migliori per determinare comunque la posizione dell'utente (ad esempio, il servizio di localizzazione di un dispositivo mobile).
Dopo averlo fatto, la risposta corretta a
http://example.com/API/SomeUnsupportedCity/HailRide
o
http://example.com/API/HailRide?city=SomeUnsupportedCity
diventa ovvio: 404 non trovato : non esiste alcuna risorsa per il passaggio a SomeUnsupportedCity.
Questa sembra una domanda buca rotonda / quadrata. Perché la tua unica risposta deve essere un codice HTTP? I codici di errore HTTP non possono coprire tutti i casi d'uso.
Tutte le tue chiamate API dovrebbero avere messaggi aggiuntivi che ritornano - cioè un piccolo messaggio di errore JSON. Dagli un 403 (perché, veramente, non hanno il permesso di usare l'API data la posizione) e restituiscono un ulteriore bit di informazioni come suggerisci.
Se non lo fai, la prossima volta chiederai quale codice di errore HTTP restituire quando l'utente ha richiesto un SUV ma è disponibile solo una Prius.
Alcuni hanno un senso.
403 Proibito, per i motivi per cui Eric Stein menziona nella sua risposta . È possibile utilizzare varie informazioni fornite dalla richiesta per determinare dove si trova il client e chi è il client e, in base a tale richiesta, il server non può o non vuole rispondere.
Tuttavia, vorrei anche proporre 451 Non disponibile per motivi legali come possibile stato di ritorno per alcuni casi. Questo stato si aspetta che tu includa (nelle intestazioni) un link alla legislazione pertinente. È specifico per i casi in cui non è legale per il client accedere alle risorse e non un caso più generale del client esistente in un'area o area non supportata.
Eviterei la serie di stati 5xx - questi spesso indicano problemi tecnici lato server. Non sembra essere il caso qui.
Se la limitazione è dovuta a motivi legali, il codice di errore HTTP appropriato è HTTP 451, "Non disponibile per motivi legali".
Questo è tipicamente usato nel caso di materiale che è stato revocato a causa di azioni o cause DMCA a causa di campagne di molestie o simili, ma spirito e lettera della definizione della risposta afferma:
This document specifies a Hypertext Transfer Protocol (HTTP) status code for use when resource access is denied as a consequence of legal demands.
Il codice stesso è un riferimento a Fahrenheit 451 di Ray Bradbury.
Spesso le persone dimenticano che i codici di stato HTTP sono estensibili.
HTTP status codes are extensible. HTTP applications are not required to understand the meaning of all registered status codes, though such understanding is obviously desirable. However, applications MUST understand the class of any status code, as indicated by the first digit, and treat any unrecognized response as being equivalent to the x00 status code of that class, with the exception that an unrecognized response MUST NOT be cached. For example, if an unrecognized status code of 431 is received by the client, it can safely assume that there was something wrong with its request and treat the response as if it had received a 400 status code. In such cases, user agents SHOULD present to the user the entity returned with the response, since that entity is likely to include human- readable information which will explain the unusual status.
Puoi sempre creare il tuo codice di stato nell'intervallo 400 per l'utilizzo da parte dell'API e applicazione client.
403 è il codice ma dovresti abbinare la descrizione dell'errore con il codice che stai dando: se dici
Service not available in your area.
quindi dovresti dare un 404 perché affermi che il servizio non è disponibile . se dici
You are not authorized for this service in your area.
quindi dovresti dare un 403 perché dichiari che il chiamante non è autorizzato .
Vorrei andare per il secondo.
All'inizio pensavo 503 perché la descrizione "servizio non disponibile" sembra allineare con il problema, ma guardando definizioni , 503 è davvero specifico per l'indisponibilità del server. Quindi, pensando di più, stai dicendo al cliente che c'è un problema con la richiesta, non che c'è un problema lato server.
403 è più vicino perché stai dicendo all'utente che hai ricevuto il messaggio e capisci ma che il server non è disposto a soddisfarlo. Ciò potrebbe confondere, quindi è possibile aggiungere una spiegazione testuale per descrivere lo scenario. Per RFC, 404 è anche un valido sostituto di questo codice.
A meno che qualcuno non abbia inventato un nuovo codice per questo, 403 o 404 sembrano essere i più vicini.
C'è un corrente Draft di Internet (che scadrà il 31 dicembre 2018) che propone modifiche allo stato HTTP 451 Non disponibile per motivi legali . La bozza suggerisce che una risposta 451 dovrebbe contenere un'intestazione geo-scope-block che dovrebbe "corrispondere a un elenco separato da virgole di codici paese alpha-2 definiti in [ISO.3166-1]". Tuttavia, la bozza specifica anche che il codice 451 non deve essere utilizzato "da un operatore per negare l'accesso a una risorsa sulla base di una politica specificata dall'operatore (al contrario di una richiesta legale posta all'operatore)".
Quindi supponendo che tu non abbia una richiesta legale per il geoblock, 451 non è il codice corretto. Qual è il codice corretto allora? Bene, numerose altre risposte hanno già suggerito 403 Proibito , ma sembrano tutte "basate sull'opinione pubblica", quindi vediamo cosa stanno facendo gli altri:
Quindi, non esiste una soluzione universale, devi solo sceglierne una che ritieni adatta alla tua situazione. Tuttavia, qualunque sia la tua scelta, assicurati di spiegare il problema reale nel corpo della risposta .
Direi che non ci sarebbe nulla di sbagliato nel solo specificare un codice di stato HTTP personalizzato, come RubberDuck ha già risposto . Un codice di stato personalizzato nella gamma da 400 potrebbe effettivamente essere anche una buona idea, perché questo attirerà sicuramente l'attenzione degli sviluppatori se vedono qualcosa come "Stato HTTP 499". Un "403" è troppo facile da passare come " OK quindi ho sbagliato la mia password, proviamo qualcos'altro invece ", e questo si traduce in ore sprecate.
Leggi altre domande sui tag api-design api http