Come dovrei fornire informazioni dettagliate su un errore, se non attraverso i codici di stato HTTP?

Non inventare codici di stato

Non è previsto che tu inventi i tuoi codici di risposta, poiché il punto dell'API è di utilizzare un'interfaccia standard che qualsiasi sviluppatore può comprendere.

Il fatto che tu mantenga sia l'API che il suo client è irrilevante: poiché tutti possono rintracciare le chiamate all'API, tutti possono implementare un client diverso. Il punto di utilizzo delle interfacce standard è anche:

• Per facilitare la manutenzione. Se in seguito la tua app verrà gestita dal tuo collega, potrà trovare la sua strada con facilità. Sarà perso se sembra che HTTP 306 significhi successo, HTTP 500 è un "Non trovato" e HTTP 909 è "Errore interno del server", a meno che l'errore non sia un'eccezione FileNotFound , nel qual caso è HTTP 404.

• Per facilitare il lavoro del tuo amministratore di sistema. Gli strumenti che trattano i log del server utilizzano i codici di stato per determinare se si tratta di un errore o meno. Due esempi concreti sono:

  1. La visualizzazione del numero di errori (HTTP 4xx e HTTP 5xx) per un determinato server e:

  2. Il tracciamento dei tentativi di hacking. Ad esempio, quando vedo un tentativo di hacking che risulta in HTTP 200, questo attira immediatamente la mia attenzione: dovrebbe invece essere HTTP 4xx.

• Per evitare problemi con il tuo server HTTP. IIS, ad esempio, può essere facilmente offeso da alcuni codici di stato, li cattura e genera le proprie risposte. La configurazione della tua app e di IIS non è sempre facile (e ho passato diversi giorni a sbattere la testa su questo problema quando ho iniziato a programmare siti Web ASP.NET).

• Per evitare problemi con i proxy. Ad esempio, se la tua API è ospitata su un server a cui si accede tramite Nginx, non sono sicuro che gli amministratori di sistema saranno felici di dedicare alcune ore a ripetere tutte le configurazioni per la tua app.

  Un esempio di base. Quando si configura il failover, utilizzo la direttiva proxy_next_upstream che indica in quali casi Nginx deve passare al macchina di failover. Guardando la documentazione, ho l'impressione che non si possa impostare la direttiva, ad esempio, su HTTP 200, quindi se la propria API usa HTTP 200 come "Errore irreversibile, tutti i dati sono corrotti, quindi potrebbe essere meglio usare un altro mirror" , sei sfortunato.

• Per evitare di reinventare la ruota. Perché dovresti perdere tempo a standardizzare i tuoi codici impostati, mentre ce n'è già uno?

• Per sfruttare il supporto di molti strumenti. Ad esempio, Fiddler si basa sul codice di risposta HTTP per colorare gli elementi. Non sono sicuro che sia facile configurarlo per utilizzare diversi stati. Allo stesso modo, diversi strumenti di test API possono fare affidamento anche sui codici di stato (mentre CURL, convenientemente, non può interessare di meno dello stato della risposta, il pacchetto requests di Python, ad esempio, eseguirà un reindirizzamento in presenza di HTTP Codice 3xx).

A proposito, i browser stessi interpretano il codice di risposta:

• Le richieste AJAX che restituiscono l'HTTP 3xx possono portare al reindirizzamento automatico.

• HTTP 4xx e HTTP 5xx sono visualizzati in rosso negli strumenti di sviluppo dei browser.

Fornisci ulteriori informazioni

Il codice di risposta diverso da HTTP 200 non significa che non puoi alimentare il client con JSON (a meno che non sia HTTP 204, nel qual caso non dovrebbe esserci contenuto). Ciò significa che sei libero di fornire tutte le informazioni che desideri al client tramite JSON. Personalmente, includo:

• L'ID dell'errore sotto forma di stringa. Ad esempio price-range-invalid o product-not-found .

• L'URI che contiene ulteriore aiuto, se pertinente (quando l'API è abbastanza grande da contenere pagine individuali per ogni messaggio di errore). Ad esempio link .

• La descrizione. Ad esempio "Il prezzo corrente è al di fuori dell'intervallo consentito. Dovrebbe essere superiore a 0 e inferiore o uguale a 50000. ".

Vedi anche in che modo altre API gestiscono gli errori e che tipo di informazioni forniscono. Ad esempio, ecco come appaiono gli errori dell'API di Google+:

HTTP 403

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "reason": "ipRefererBlocked",
    "message": "There is a per-IP or per-Referer restriction configured on your API key and the request does not match these restrictions. Please use the Google Developers Console to update your API key configuration if request from this IP or referer should be allowed.",
    "extendedHelp": "https://console.developers.google.com"
   }
  ],
  "code": 403,
  "message": "There is a per-IP or per-Referer restriction configured on your API key and the request does not match these restrictions. Please use the Google Developers Console to update your API key configuration if request from this IP or referer should be allowed."
 }
}

Non fornire troppe informazioni

Infine, assicurati che non includa l'eccezione stessa nei dettagli , poiché potrebbe contenere informazioni riservate e rappresentare un percorso da esplorare per un hacker (inclusa la traccia dello stack).

Ad esempio, alcuni siti Web PHP, quando si verifica un errore relativo al database, mostrano all'utente la query SQL e l'errore. Per un hacker, questo è molto conveniente. Per un utente legittimo, questo è solo scortese e inutile. Non farlo.

Gli unici codici di stato necessari da HTTP sono 200 per Success e 500 per errore, in modo che tu sappia se stai avendo una conversazione riuscita o meno. (Forse anche 404 se la tua API non è l'unica applicazione in esecuzione sul tuo server.)

Una volta stabilita una conversazione riuscita, qualsiasi altro errore che potrebbe verificarsi non ha assolutamente nulla a che fare con il protocollo di comunicazione ; si tratta di un errore specifico della tua applicazione, quindi dovrebbe essere comunicato all'interno del tuo XML o JSON o qualunque cosa tu stia utilizzando per implementare la tua API.

Tieni sempre presente questa domanda:

What if you were communicating over a medium other than HTTP?