Implementando Negociação de Conteúdo com Base nos Cabeçalhos HTTP

Os aplicativos Representational State Transfer (REST) podem retornar representações de recursos diferentes. É possível usar a negociação de conteúdo com base nos cabeçalhos HTTP Accept para determinar o formato de conteúdo que é usado para trocar dados entre os servidores e clientes.

Sobre Esta Tarefa

Os recursos podem representar dados em formatos diferentes. É possível implementar negociação de conteúdo com base nas URLs, nos parâmetros de pedidos ou nos cabeçalhos HTTP. Essa tarefa descreve a negociação de conteúdo com base nos cabeçalhos HTTP Accept para enviar e receber formatos de dados diferentes.

Quando um navegador da Web faz um pedido, ele envia informações sobre o que ele está procurando para o servidor em cabeçalhos. Um desses cabeçalhos é o cabeçalho de Aceitação. O cabeçalho de Aceitação informa ao servidor quais formatos ou tipos MIME o cliente está procurando. É possível usar os cabeçalhos HTTP Accept para determinar o formato de conteúdo usado para trocar dados.

Enquanto que o cabeçalho Accept não é visível como URLs ou parâmetros, esse cabeçalho é o método mais flexível de manipular negociação de conteúdo. Também é possível usar os cabeçalhos HTTP Accept, Accept-Charset, Accept-Language e Accept-Encoding para determinar o tipo de conteúdo que é retornado do servidor.

Usando os cabeçalhos HTTP, é possível designar graus de qualidade para as respostas aceitáveis. Por exemplo, um cliente pode indicar que XML é o tipo de conteúdo de resposta preferido. Entretanto, se XML não estiver disponível, o cliente pode aceitar JSON ou um texto simples para o formato.

Por exemplo, se o cabeçalho de Aceitação contiver um valor como application/json; q=1.0, text/xml;q=0.5, application/xml;q=0.5, esse valor indicará que JSON é preferencial, mas XML também é aceitável.

Em outros métodos de negociação de conteúdo, normalmente apenas um tipo de resposta preferido existe. Entretanto, é possível usar os cabeçalhos HTTP Accept para informar o serviço de todos os tipos possíveis que são aceitos para o cliente em um pedido. Além disso, a HTTP Accept e seus cabeçalhos relacionados fazem parte do padrão HTTP.

É importante considerar os seguintes aspectos ao implementar a negociação de conteúdo usando cabeçalhos HTTP. Alguns clientes podem enviar valores incorretos e alguns serviços podem não respeitar os cabeçalhos HTTP Accept. Além disso, processar todos os cabeçalhos HTTP e calcular a resposta ideal não é tão direto do que solicitar o conteúdo com base em uma URL ou um parâmetro de pedido.

Procedimento

  1. Inclua o parâmetro @javax.ws.rs.core.Context javax.ws.rs.core.Request no método de recurso.
  2. Use o objeto javax.ws.rs.core.Variant.VariantListBuilder para criar uma lista de variantes de reposta possíveis que o serviço suporta.
  3. Teste uma resposta aceitável.

    Use o método javax.ws.rs.core.Request.selectVariant(java.util.List<Variant>variant) para determinar se você recebe uma resposta aceitável para enviar para o cliente. Uma lista de variantes de resposta possíveis é transmitida para o método. Uma variante representa uma combinação de tipo de mídia, idioma e de codificação. Consulte a documentação da API javax.ws.rs.core.Variant e javax.ws.rs.core.Variant.VariantListBuilder para obter informações adicionais sobre a criação de uma lista de variantes.

    Com base nas variantes de resposta possíveis e nos cabeçalhos HTTP de pedido recebido, o método selectVariant(java.util.List<Variant> variant) retorna a melhor variante de reposta possível que corresponde aos cabeçalhos HTTP.

    O seguinte exemplo demonstra o uso a anotação @javax.ws.rs.core.Context para injetar o tipo javax.ws.rs.core.Request. O tipo javax.ws.rs.core.Request pode ajudar a determinar a variante de resposta otimizada. Nesse exemplo, um objeto Request é transmitido pelo ambiente de tempo de execução quando o método de recurso é chamado.
    @Path("/resources")
    public class Resource
    {
        @Path("{resourceID}")
        @GET
        public Response getResource(@PathParam("resourceID") String resourceID, @Context Request req)
        {
            /* This method builds a list of possible variants. */
            /* You must call Variant.VariantListBuilder.add() object before calling the Variant.VariantListBuilder.build() object. */
            List<Variant> responseVariants =
                     Variant
                         .mediaTypes(
                                     MediaType.valueOf(MediaType.APPLICATION_XML + ";charset=UTF-8"),
                                     MediaType.valueOf(MediaType.APPLICATION_XML + ";charset=shift_jis"),
                                     MediaType
                                         .valueOf(MediaType.APPLICATION_JSON))
                         .encodings("gzip", "identity", "deflate").languages(Locale.ENGLISH,
                                                                             Locale.FRENCH,
                                                                             Locale.US).add().build();
    
              /* Based on the Accept* headers, an acceptable response variant is chosen.  If there is no acceptable variant,
              selectVariant will return a null value. */
    
             Variant bestResponseVariant = req.selectVariant(responseVariants);
             if(bestResponseVariant == null) {
    
                 /* Based on results, the optimal response variant can not be determined from the list given.  */ 
    
                return Response.notAcceptable().build();
             }
             MediaType responseMediaType = bestResponseVariant.getMediaType();
    
             /* This instruction obtains the acceptable language and modifies the response entity. */
    
             Locale responseLocale = bestResponseVariant.getLanguage();
             if(responseMediaType.isCompatible(MediaType.APPLICATION_XML_TYPE)) {
                 return Response.ok(/* entity in XML format */).type(MediaType.APPLICATION_XML).build();
             } else if (responseMediaType.isCompatible(MediaType.APPLICATION_JSON_TYPE)) {
                 	return Response.ok(/* The entity is  in JSON format */)
    
    				.type(MediaType.APPLICATION_JSON).build();
             }
             return Response.notAcceptable(Variant.mediaTypes(MediaType.APPLICATION_XML_TYPE,
    				 MediaType.APPLICATION_JSON_TYPE).add().build()).build();
         }
     }

Resultados

Você implementou a negociação de conteúdo usando os cabeçalhos de Aceitação para determinar os formatos de recursos que representam dados.


Ícone que indica o tipo de tópico Tópico de Tarefa



Ícone de registro de data e hora Última atualização: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_jaxrs_contentnegotiation_httphead
Nome do arquivo: twbs_jaxrs_contentnegotiation_httphead.html