Va bene restituire HTML da un'API JSON?

24

Nel mio progetto corrente sono responsabile dell'implementazione di un servizio che prevede il consumo di API RESTful appena create, documentate come supporto esclusivo di JSON.

Il client effettua costantemente richieste con l'intestazione di accettazione di 'application / json' e il tipo di contenuto di 'application / json'. Tuttavia alcuni endpoint inviano una risposta con un tipo di contenuto di HTML, anche un corpo HTML. Per me questo è chiaramente l'approccio sbagliato e non può mai essere giustificato.

Nel corso del progetto, questa stessa pratica è stata applicata a due diversi fornitori e a due servizi diversi. Mi sono trovato a dover giustificare il motivo per cui i servizi dovevano essere cambiati. I venditori hanno affermato che il client dovrebbe far fronte a questo e anche la mia libreria di scelta REST è stata messa in discussione (RestEasy) perché non è in grado di farcela con questa impostazione predefinita "out the box".

Questo è stato un punto importante di frustrazione. Non riesco a trovare molti riferimenti per sostenere il mio argomento, presumo che ciò sia dovuto al fatto che il punto è discutibile in quanto è così ovvio.

La domanda è: mi manca qualcosa? sono pedante di questo? È OK avere un'API JSON che non ha un tipo di contenuto di applicazione / json in questo scenario? Le referenze sarebbero apprezzate. Come risolvi questa situazione da un punto di vista commerciale?

    
posta phillip.darley 10.08.2013 - 09:28
fonte

3 risposte

26

Quando invii un'intestazione accept che richiede un tipo di supporto specifico, il server non deve restituire qualcos'altro, e sicuramente non con un codice di stato 200 OK

Da Restpatterns.org :

If no Accept header field is present, then it is assumed that the client accepts all media types. If an Accept header field is present, and if the server cannot send a response which is acceptable according to the combined Accept field value, then the server SHOULD send a 406 (not acceptable) response.

(Enfasi mia)

Restpatterns.org prende questo dallo standard HTTP attuale: Definizioni dei campi di intestazione - Accetta

In breve: non sei pedante. I servizi non seguono lo standard HTTP se restituiscono HTML quando l'intestazione accept specifica loro di restituire application/json e nient'altro.

    
risposta data 10.08.2013 - 12:55
fonte
9

Che cosa intendi con "RESTful JSON API"? Penso che il primo problema qui sia che stai mescolando concetti (o forse qualcuno tra te e le tue controparti tecniche presso i tuoi "fornitori").

Un'API RESTful (indipendentemente dal fatto che tu stia parlando davvero al livello 1 o qualcosa di livello 3 o superiore cfr link ) riguarda il modo in cui interagisci con l'API non sul formato del contenuto inviato o ricevuto da. Non si tratta nemmeno di protocolli o meccanismi di trasporto ...

Allo stesso modo, un'API JSON è un'API che supporta l'uso di JSON come formato di dati - può essere o non essere riposante, può o non può essere implementata usando HTTP e (e questo è il punto chiave) può o non può supportare esclusivamente JSON.

Un'API buona in esecuzione su HTTP (è ragionevole supporre che nel contesto si parli di un'API esposta tramite HTTP) dovrebbe consentire di richiedere il contenuto in una varietà di formati e tali formati possono (e forse dovrebbe) includere HTML così come JSON e XML. Perché? Beh, renderebbe l'apprendimento dell'API molto più semplice, concettualmente fornisce un UX basato su browser istantaneo per qualsiasi scopo e così via ...

La domanda interessante diventa allora se la mia API, che supporta una varietà di formati di contenuto, viene chiamata senza che venga detto quale formato il client si aspetta e quale formato dovrebbe restituire ...? Questo tende ad un argomento religioso - ma HTML offre al provider la possibilità di includere informazioni utili (come "ricorda di impostare l'intestazione di accettazione del contenuto").

Per rispondere alla domanda un'API, una che è riposante e una che supporti json, dovrebbe assolutamente essere in grado di restituire HTML se questo è il contenuto richiesto.

    
risposta data 10.08.2013 - 11:17
fonte
5

The client consistently makes requests with the accept header of 'application/json' and content-type of 'application/json'

Sì, questa è la cosa giusta da fare, ma non significa che il venditore si preoccupi. Mentre capisco perfettamente la tua frustrazione, perché penso anche che un servizio JSON dovrebbe sempre dare una risposta JSON, ma ci sono molti esempi in cui non è il caso.

Throughout the project this same practice has been applied across two different vendors and two different services. I found myself having to justify why the services needed to be changed. The vendors stated that the client should cope with this and even my REST library of choice has been questioned (RestEasy) because it doesn't cope with this by default 'out the box'.

Bene, devo essere d'accordo con il venditore. È il loro servizio e finché documentano chiaramente i casi speciali per usarlo, allora non si può davvero imporre che lo cambino. È uno svantaggio per loro dato che gli sviluppatori saranno lenti nell'adottare le loro API e, se ascoltassero ciò di cui hanno bisogno gli sviluppatori, lo cambierebbero, ma purtroppo non c'è alcuna regola che loro debbano seguire gli standard.

The question is am I missing something?

Le intestazioni di richieste non significano nulla a meno che non vengano interrotte correttamente dall'altra parte. So che se sviluppo un'API web utilizzando PHP, allora al diavolo le intestazioni delle richieste. Posso rispondere con quello che voglio. Mentre un servizio configurato in IIS con C # offre una gestione molto più semplice delle intestazioni delle richieste, del loro tipo e della gestione del tipo di risposta. Ha molto a che fare con gli strumenti utilizzati dal venditore per costruire l'API.

I'm I being pedantic about this?

Sì e No. Ho amici sviluppatori che non sarebbero in grado di superare questo. Diventerebbero così fissi dal problema e incapaci di procedere con altre attività finché l'API non funzionasse nel modo in cui si aspettavano che funzionasse. Ora è pedante.

È un problema perché il venditore ha creato "più lavoro" per completare le tue attività. Chiunque sarebbe frustrato da questo. So che lo sarei.

Is it OK to have a JSON API that doesn't have a content-type of application/json in this scenario?

Assolutamente, ma non è una buona pratica.

Un client può solo dire al server qual è il tipo di contesto di request . Non ha la capacità di imporre un tipo di contenuto per response . Il client può solo informare il server che sarà accept una raccolta di possibili tipi di contenuto.

Definizioni dei campi di intestazione

The Accept request-header field can be used to specify certain media types which are acceptable for the response. Accept headers can be used to indicate that the request is specifically limited to a small set of desired types, as in the case of a request for an in-line image.

È possibile che un cliente richieda un'immagine di image/jpeg , ma le risposte del server con text/html e un codice di stato di 404 se l'immagine non è stata trovata. I server possono anche rispondere in modo errato. Esistono molti siti Web Wordpress che rispondono con text/html e codice di stato 200 per le pagine file non trovate.

Questa è la pratica BAD sulla parte del server. Quello che sto cercando di dirti è che è assolutamente possibile, e succede spesso. Le persone non sanno cosa stanno facendo quando configurano queste cose.

References would be appreciated. How do you resolve this situation from a commercial point of view?

Ho incontrato questo problema su alcuni progetti. Hai post di dati JSON sul server e restituisce una risposta JSON o HTML.

In realtà non è un grosso problema sapere quale tipo era nella risposta. Se il primo carattere è { o [ puoi assumere JSON. Se è < puoi assumere HTML. È così che l'ho gestito in passato. A volte il programmatore che ha scritto l'API sa tutto riguardo le intestazioni HTTP. Tutto torna come text/html risposte. Se sei fortunato hanno Apache configurato per default su text/plain che a volte può aiutare.

Questi problemi esistono e continueranno a esistere molto nel futuro. La comunicazione da server a server è di gran lunga un'attività non regolamentata. Non esiste un ente governativo che esca un fornitore da un sindacato per un server che fornisce risposte HTTP sbagliate.

    
risposta data 10.08.2013 - 13:59
fonte

Leggi altre domande sui tag