Mimetypes per un'API RESTful

Question

L'API Sun Cloud a http://kenai.com/projects/suncloudapis/pages/Home è un buon esempio da seguire per un'API RESTful. Fedele ai principi RESTful, quando OTTIENI una risorsa non ottieni né più né meno una rappresentazione di quella risorsa.

L'intestazione Content-Type nella risposta indica esattamente il tipo di tale risorsa, ad esempio application/vnd.com.sun.cloud.Snapshot + json. Sun ha registrato questi mimetipi con lo IANA.

Quanto è pratico questo in generale al momento? La maggior parte delle API che ho visto hanno utilizzato il Content-Type di "application/json". Questo ti dice che la risposta è JSON ma niente di più. Devi avere qualcosa nell'oggetto JSON, come una proprietà di "tipo", per sapere di cosa si tratta.

Sto progettando un'API RESTful (che non sarà resa pubblica, quindi non registrerei i mimetypes). Ho usato RESTEasy e trovo che anche se specifichi un mimetype completo, il Content-Type nell'intestazione della risposta sarà esattamente ciò che l'intestazione della richiesta Accept ha specificato. Se la richiesta richiede "application/* + json", per impostazione predefinita l'intestazione della risposta avrà "application/* + json". Posso probabilmente sistemarlo cambiando l'intestazione prima che la risposta si spenga, ma dovrei provare a farlo? O la risposta dovrebbe avere un carattere jolly come ha fatto la richiesta?

Oppure devo semplicemente pubblicare "application/json" come la maggior parte delle API sembrano fare?

pensieri supplementari aggiunti successivamente:

Un altro modo per affermare la domanda è: Devo usare HTTP come protocollo, o dovrei usare HTTP solo come un meccanismo di trasporto per avvolgere il mio protocollo?

Per utilizzare HTTP come protocollo, il corpo dell'entità della risposta contiene la rappresentazione dell'oggetto richiesto (o la rappresentazione di un oggetto messaggio di errore), l'intestazione "Content-Type" contiene il tipo esatto dell'oggetto, e l'intestazione "Stato" contiene un codice di successo o di errore.

Per utilizzare HTTP come semplice meccanismo di trasporto, l'intestazione "Status" è sempre impostata su 200 OK, il "Content-Type" è qualcosa di generico come "application/json" e il corpo dell'entità contiene qualcosa che ha esso stesso un oggetto, un tipo di oggetto, un codice di errore e qualsiasi altra cosa desideri. Se il tuo protocollo è RESTful, allora l'intero schema è RESTful. (HTTP è un protocollo RESTful ma non l'unico possibile.)

Il proprio protocollo sarà opaco a tutti i livelli di trasporto. Se si utilizza HTTP come protocollo, tutti i livelli di trasporto lo capiranno e potrebbero fare cose che non si desidera; ad esempio un browser intercetterà una risposta "401 non autorizzata" e aprirà una finestra di dialogo di accesso, anche se si vuole gestirlo da soli.

Answer 1

O dovrei semplicemente servire "application/json" come la maggior parte delle API sembrano fare?

Non credo.

Un tipo di supporto è l'unico punto di accoppiamento tra l'applicazione web RESTful ei client che lo utilizzano. La documentazione dei tuoi tipi di media è la documentazione della tua API. I tuoi tipi di media sono il contratto tra i tuoi clienti e la tua applicazione. Elimina il tipo di supporto specifico ed elimini un elemento importante che rende praticabile il REST.

Sun ha registrato questi mimetipi con lo IANA.

Impossibile trovare any mention of that here. AFAIK, non è necessario registrare effettivamente il tipo di supporto personalizzato con IANA. La convenzione sembra essere quella di utilizzare la notazione invertita del dominio dell'applicazione/vnd.com.example.app.foo + json, che impedisce i conflitti nello spazio dei nomi. Se e quando il tuo tipo di media diventa stabile e pubblico, potrebbe essere una buona idea, ma non c'è alcun obbligo. Potrebbe essere sbagliato su questo, però.

Answer 2

Si ottiene qualsiasi valore specificando un mimetype completo? Faresti qualcosa con il mimetype completo diverso da quello che faresti se il mimetype fosse application/json?

I miei 2 centesimi- Se l'API non verrà resa pubblica, non vedo alcun motivo per un mimetype completo. Un mimetype di application/json dovrebbe essere più che sufficiente. Conoscete già il tipo di JSON che la risposta sta restituendo. Se l'API alla fine diventa pubblica, quindi preoccuparsi di un completo mimetype ... o semplicemente lasciare che le persone capiscano.

Answer 3

Uso i miei tipi di supporto vnd.mycompany.mymediatype + xml per molte delle mie rappresentazioni. Sul client invio alla classe controller appropriata in base al tipo di media della rappresentazione restituita. Ciò consente realmente al server di controllare il comportamento della mia applicazione client in risposta all'utente che segue un collegamento.

Personalmente, credo che l'uso di application/xml e application/json sia una delle peggiori scelte che puoi fare se speri di supportare i client REST. L'unica eccezione a questo è quando il client utilizza solo il codice scaricato (come Javascript) per interpretare i dati.