asp.net-web-api
Negoziazione del contenuto dell'API Web ASP.NET

Informazioni di base sulla negoziazione del contenuto dell'API Web ASP.NET

La negoziazione del contenuto può essere definita come il processo di selezione della migliore rappresentazione per una determinata risorsa. Quindi la negoziazione del contenuto significa che il client e il server possono negoziare tra loro in modo che il cliente possa ottenere i dati in base al formato richiesto.

Ci sono tre punti da cui dipende internet,

• La risorsa
• Un puntatore a risorsa (URL)
• Rappresentazione di risorse

Il terzo punto è più importante degli altri due, perché tutto funziona sulla base di come possiamo vedere la risorsa. Possiamo rappresentare una risorsa in due formati.

1. Formato XML (Extensible Markup Language)
2. Formato JSON (notazione oggetto JavaScript)

Uno degli standard del servizio RESTful è che, il client dovrebbe avere la capacità di decidere in quale formato vogliono la risposta sia in JSON che in XML. Una richiesta inviata al server include un'intestazione Accept. Utilizzando l'intestazione Accept il client può specificare il formato per la risposta.

Per esempio,

Accept: application/xml risultati restituiti da Accept: application/xml in formato XML

Accept: application/json restituisce il risultato in formato JSON

A seconda del valore di intestazione Accept nella richiesta, il server invia la risposta. Questo è chiamato Content Negotiation.

Cosa succede dietro la scena quando richiediamo dati in formato specifico?

Il controller API Web ASP.NET genera i dati che vogliamo inviare al client e consegna i dati alla pipeline dell'API Web che cerca l'intestazione Accept del client. Quindi, scegliere un formattatore appropriato per formattare i dati.

Poiché l'API Web ASP.NET è notevolmente estensibile, possiamo anche specificare più valori per l'intestazione di accettazione nell'intestazione della richiesta.

Accept: application/xml,application/json

Nel caso precedente, il server sceglie il primo formattatore per formattare i dati di risposta.

Possiamo anche specificare il fattore di qualità nell'intestazione di accettazione. In questo caso, il server sceglie un formato con un fattore di qualità più elevato.

Accept: application/json;q=0.8,application/xml;q=0.5

Se non si specifica alcuna intestazione Accept, il server predefinito sceglie il formattatore JSON.

Quando la risposta viene inviata al client nel formato richiesto, si noti che l'intestazione Content-Type della risposta è impostata sul valore appropriato. Ad esempio, se il client ha richiesto application/xml , il server invia i dati in formato XML e imposta anche Content-Type=application/xml .

I formattatori vengono utilizzati dal server per entrambi i messaggi di richiesta e risposta. Quando il client invia una richiesta al server, impostiamo l'intestazione Content-Type sul valore appropriato per consentire al server di conoscere il formato dei dati che stiamo inviando.

Ad esempio, se il client invia dati JSON, l'intestazione Content-Type è impostata su application/json . Il server sa che ha a che fare con i dati JSON, quindi usa JSON formattatter per convertire i dati JSON in .NET Type. Analogamente, quando una risposta viene inviata dal server al client, a seconda del valore di intestazione Accept, viene utilizzato il formattatore appropriato per convertire il tipo .NET in JSON, XML, ecc.

Esempio di diversi tipi di formato di risposta:

application / json:

{
  "Email": "sample string 1",
  "HasRegistered": true,
  "LoginProvider": "sample string 3"
}

application / xml:

<UserInfoViewModel xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/WebApiDemo.Models">
  <Email>sample string 1</Email>
  <HasRegistered>true</HasRegistered>
  <LoginProvider>sample string 3</LoginProvider>
</UserInfoViewModel>

Le moderne applicazioni web possono fornire dati in varie lingue e formati. Pertanto, se sviluppiamo la nostra API per coprire gli utenti globali in tutto il mondo, la Negoziazione dei contenuti è rilevante.

Negoziazione del contenuto nell'API Web

Capire il concetto

Per comprendere la negoziazione del contenuto nell'API Web, è importante comprendere il termine Resource .

Sul web, qualsiasi informazione a cui possiamo accedere può essere indicata come HTTP resource . C'è una quantità enorme di materiale da visualizzare sul web che ha diversi tipi di contenuti come documenti html, immagini, video, audio, file eseguibili, fogli di calcolo, ecc. Possiamo ottenere qualsiasi risorsa facendo una richiesta http alla risorsa uri. La risposta http per la richiesta, restituisce la risorsa e specifica anche il tipo di contenuto, che è also known as media type .

Per accedere a qualsiasi risorsa, il cliente può effettuare una richiesta http fornendo uri specifici della risorsa e i verbi http. Tuttavia, in aggiunta a questo, il client può anche specificare il tipo di accettazione che è il formato del contenuto che l'utente sta cercando. Il "tipo di accettazione" può essere definito nelle intestazioni delle richieste http come intestazione “accept” .

Il server quindi controlla l'intestazione "accetta" dalle richieste e restituisce la risposta nel formato specificato, se disponibile. Si noti che il server può restituire la risposta nella rappresentazione richiesta solo se è disponibile . Se la rappresentazione richiesta non è disponibile, restituisce la risorsa nella rappresentazione predefinita. Questo è il motivo per cui è chiamato negoziazione del contenuto.

Un esempio pratico

Ad esempio, supponiamo che tu stia facendo una richiesta a http://example.com/customer/1 per ottenere le informazioni del cliente con l'id 1. Se non specifichi l'intestazione "accept" nella richiesta, il il server restituirà la rappresentazione predefinita di questa risorsa.

Supponiamo che il server possa restituire json and xml both le informazioni sul cliente in json and xml both . Ora, è sul client per specificare il formato richiesto delle informazioni sul cliente nell'intestazione "accetta" nella richiesta. Il valore dell'intestazione “accept” può essere “application/json” per la rappresentazione json, o “text/xml” per la rappresentazione xml. Il server restituirà quindi la risposta secondo il formato richiesto.

Se il formato richiesto è "text / html" che non è supportato da questo host (come in questo esempio), simply return the resource in the default format . La risposta http contiene un'intestazione “content-type” che indica al client il formato della risorsa.

Si noti che anche nel caso in cui la rappresentazione richiesta della risorsa non sia disponibile, viene comunque restituita la rappresentazione predefinita della risorsa.

Questo è il motivo per cui viene indicato come negoziazione del contenuto .

Il client negozia la rappresentazione della risposta, tuttavia, se non è disponibile, ottiene quella predefinita.

Come configurare in Web API

Nell'API Web, la negoziazione del contenuto può essere configurata nella classe WebAPIConfig come

config.Formatters.JsonFormatter.SupportedMediaTypes.Add(new System.Net.Http.Headers.MediaTypeHeaderValue("text/html"));

È anche possibile sovrascrivere la negoziazione del contenuto predefinita nell'API Web implementando l'interfaccia IContentNegotiator e il relativo metodo Negotiate, quindi configurarlo nella riga della pipe di richiesta dell'API Web, nel file WebAPI.config come indicato di seguito:

GlobalConfiguration.Configuration.Services.Replace(typeof(IContentNegotiator), new CustomContentNegotiator());

Di seguito è riportato un esempio di implementazione del metodo Negotiate.

public class CustomContentNegotiator : DefaultContentNegotiator
    {
        public override ContentNegotiationResult Negotiate(Type type, HttpRequestMessage request, IEnumerable<MediaTypeFormatter> formatters)
        {
            var result = new ContentNegotiationResult(new JsonMediaTypeFormatter(), new MediaTypeHeaderValue("application/json"));
            return result;
        }