O documento aborda boas práticas no desenvolvimento de web services, destacando os erros comuns em SOAP (jax-ws) e RESTful (jax-rs) e suas soluções. Discute temas como declaração de namespace, tipos de dados, design de URI, versionamento, granularidade, cache e documentação necessária para serviços eficazes. Em suma, enfatiza a importância de um design claro e a manutenção de versões para garantir aplicações compreensíveis e de fácil manutenção.

1. Boas Práticas com Web
Services

2. Introdução
Quando utilizamos Web Services, no desenvolvimento web, quais
são os erros mais comuns que os desenvolvedores cometem ?
Quais as consequências, de deixar uma aplicação confusa de se
entender e de difícil manutenção ?

3. Web Services
Existem dois tipos de Web Services que serão abordados, SOAP e RESTful.
A JAX-WS - é uma especificação Java para utilizar Web Services baseados em xml,
através do protocolo SOAP.
A JAX-RS - é uma especificação Java para utilizar Web Services RESTful, através do
protocolo HTTP.
Ambos tipos de Web Services, com serviços monolíticos, pois para microsserviços, existe
uma outra JSR.
Existe uma JSR para cada tipo de Web Service:
- JSR-224: JavaTM API para Web Services baseados em XML (JAX-WS) especificação 2.0;
- JSR 339: JAX-RS 2.0: A API Java para Web Services;
- JSR 370: JavaTM API para RESTful Web Services Especificação (JAX-RS 2.1);

4. Web Services – SOAP (JAX-WS) e RESTful (JAX-RS)

5. Como resolver os erros mais comuns no desenvolvimento de
Web Services ?
Como deixar uma aplicação fácil de se entender e de simples
manutenção ?
Solução

6. SOAP – Erros mais comuns cometidos
1 - Declaração de Namespace inadequada:
- Fornecer namespaces incorretos e usá-los no documento wsdl criará um problema na
resolução dos elementos usando os namespaces.
2 - Problemas com o tipo de dados:
- Os tipos de dados complexos causarão a serialização do XML para a conversão de do tipo de
dados Java, e afetarão o desempenho. Para evitar essa perda de desempenho, use os tipos
de dados mais simples, como String, Integer e BigDecimal.
3 - Chamadas freqüentes e repetidas, de clientes ao mesmo serviço criam tráfego de rede e
criam problemas de desempenho:
- A solução é fazer uma chamada assíncrona.
4 - Elemento de mensagem SOAP desnecessário ou complexo aumentará o tempo de
processamento para analisar as mensagens SOAP.
5 - Marshalling e unmarshalling também causam um enorme impacto no tempo de
processamento. Mais elementos XML aninhados resultam em maior tempo de empacotamento
e desempacotamento. A solução é usar um design pattern singleton neste processo.

7. RESTful – Erros mais comuns cometidos
1 - Design da URI:
- Os URI’s são a parte principal de uma interface do Web Service. É muito difícil de alterá-lo
quando os serviços são publicados e usados ​​por clientes internos/externos;
Exemplo de URI: http://localhost:8080/cliente/{id}/{nome}
- A URI deve ser conciso;
- Deve ser fácil de lembrar;
- Identifique de forma não ambígua o recurso de destino;
- Deve ter apenas substantivos como parte do URI;
- O URI deve identificar o recurso e não a ação;
- A primeira parte do URI deve identificar o módulo (por exemplo cliente, pedido, compra,
usuário, etc.) e todos os URI’s desse módulo devem estar abaixo dele hierarquicamente.
Exemplo:
Chamada – http://localhost:8080/nome_aplicacao/cliente/1
Na aplicação nome_aplicacao, chamando o módulo cliente, consultando pelo código
de cliente 1.
Chamada – http://localhost:8080/nome_aplicacao/pedido/123
Na aplicação nome_aplicacao, chamando o módulo pedido, consultando pelo código
de pedido 123.

8. RESTful – Erros mais comuns cometidos
2 - Versionamento:
Com o passar do tempo, terá um momento, em que chegará uma nova versão de serviços que
pode não ser compatível com versões anteriores, e gostaríamos de manter duas versões em
paralelo, durante o período de atualização do cliente. O controle de versão deve estar
embutido nos serviços desde o início, já que é difícil introduzir isso, depois que os serviços já
tiverem sido publicados. O cliente deve transmitir as informações da versão no cabeçalho de
solicitação, no Header no item “Accept”, exemplo: Accept: application/xml;version=1.0,
que o servidor pode usar. Caso a versão passada não seja suportada, o servidor vai devolver
um objeto Response, responder com o Código de Resposta Http 415 e uma mensagem
informativa.
3 - Granularidade:
Os serviços devem ser de granulação grossa. Os serviços normalmente farão mapeamentos
para objetos de domínio de nível superior. Em um modelo de domínio bem projetado, as
operações em objetos de domínio de alto nível serão mapeadas para os casos de uso de
negócios. Deve-se ter expostos as tarefas principais através de métodos, e não expor as
sub-tarefas. Expor cada objeto persistente via Web Services, não é uma boa prática.
Não se deve expor o design da aplicação interna, adiciona métodos redundantes, ou não
usados, torna o Web Service difícil de se entender, e de utilizar.

9. RESTful – Erros mais comuns cometidos
4 - Cache:
Os Web Services devem armazenar em cache somente solicitações GET com status de bem-
sucedidas, success. O cache em várias camadas é necessário para se ter um bom desempenho. O
cache de camada persistente é uma obrigação. Além disso, o cache no nível do método pode ser
também adicionado. Os Web Services também devem incluir o cabeçalho de controle de cache em
resposta, para que o cliente possa decidir se podem ou não armazenar a resposta em cache. Para
respostas armazenadas, o servidor deve definir o cabeçalho HTTP 'Vary' para indicar que a resposta
pode ser armazenada em cache com base na URL mais o tipo do conteúdo retornado: Content-Type:
Vary: Content-Type
5 - Documentação:
O documento deve incluir para cada método do Web Service:
- Método HTTP;
- URI;
- Cabeçalhos de solicitação HTTP de aceitação e tipo de conteúdo (Accept e o Content-Type HTTP);
- Todos os códigos HTTP de resposta possíveis;
- Qualquer tipo de cabeçalho personalizado;
- Um exemplo da resposta do Web Service;
- Exemplo de corpo da solicitação para requisições do tipo PUT, POST;
- Os esquemas (schema) os arquivos xsd para cada solicitação e resposta.

10. Exemplos Práticos
Serão exibidos agora, exemplos práticos de uma aplicação Java
Web utilizando Web Services SOAP(JAX-WS) e RESTful (JAX-RS)

11. Boas Práticas com Web Services
Evaldo Antonio Pinto Junior
Site pessoal: http://www.tidicas.com.br
Email: contato@tidicas.com.br
Dúvidas ?
Obrigado.