Arquivo para dezembro de 2015

Alterando o diretório padrão dos artefatos Maven

Algumas vezes pode ser interessante mudar o diretório padrão em que o repositório do Maven armazena seus artefatos. Por padrão eles são salvos na pasta.

 C:\Users\seu_usuario\.m2\repository

No diretório “C:\Program Files\Apache Software Foundation\{{sua_versao_maven}}\conf\” temos o arquivo settings.xml abra esse arquivo em um editor de texto plano e logo no início do arquivo adicione a tag localRepository especificando onde seus artefatos serão salvos.

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
				
		<!-- Essa é a tag mágica -->
		<localRepository>D:\MavenRepository\repository</localRepository>
		

Agora sempre que precisar de um novo artefato o Maven vai procurar nesse diretório e caso não o encontre irá baixa-lo dos repositórios remotos.

Tags: ,

HTTP Status Codes em Serviços REST



Uma boa prática ao se desenvolver serviços REST é retornar status codes adequados a cada operação executada. Isso tem uma importância ainda maior quando se trata de uma exceção, uma vez que diferentementemente de um serviço SOAP uma aplicação verdadeiramente REST não retorna a exception para o usuário. Sendo assim é fortemente recomendado que ao se desenvolver uma API REST se vá além dos status code 200 e 500 OK e falha respectivamente.


200 OK – Request de criação ou deleção executada com sucesso.


201 Created – Criação de uma fila, topico, fila temporária, tópico temporária, session, producer, consumer, listener, queue browser ou menssagem realizada com sucesso.


204 No Content – deleção de uma fila, tópico, sessão, producer ou listener bem sucedida mas sem retorno de conteúdo.


400 Bad Request – O path informado está em umformato incorreto, um parametro ou valor do corpo da requisição não está formatado corretamente ou um parâmetro onbrigatório não foi informado,
ou está formatado corretamente mas pode estar eventualmente inválido (por exemplo, o ID informado não exite – NullPointerException, o conteúdo retornado é muito grande ou o ID informado já está em uso).


403 Forbidden – O cliente não tem permissão para executar requisições na operação em questão.


404 Not Found – o objeto requisitado pelo path não existe(NullPointerException).


405 Method Not Allowed – O usuário não tem permissão de acesso ao path.


409 Conflict – Um objeto já foi criado com as mesmas informações.


500 Internal Server Error – Ocorreu uma falha no servidor, podendo ser desde uma falha no SQL por exemplo.

A prática de retornar os status code corretos torna seus serviços mais amigáveis ao cliente facilitando a integração com outros sistemas. Nos próximos posts botaremos a mão na massa desenvolvendo a nossa propria API/Serviço REST.


Botando em prática


Em breve estarão disponíveis dois posts Criando o primeiro endpoint REST com SpringBoot e Documentando aplicações RESTfull com SpringBoot e Swagger com exemplos práticos.


Referências


DZone

Java World

StackOverflow

Oracle

Tags: , , , ,

RESTful Web Services

Dando seqüência a série de postagens sobre Web-services neste post, discutiremos sobre a JAX-RS 2.0 a especificação para serviços baseados em RESTful. No mundo REST, você pode acessar tudo como um recurso e eles possuem um identificador único a URI(Uniform Resource Identifier). Um servidor REST e seus clientes interagem usando o protocolo HTTP e seus quatro verbos mais conhecidos que são:


POST – CREATE/para inserir recurso


O verbo HTTP POST é mais freqüentemente usado para criar novos recursos — inserir um novo item na base. Em uma aplicação REST perfeita quando uma operação é executada com sucesso, retorna-se o idempotente portanto seu uso não é recomendado quando se precisa desse tipo de comportamento em uma requisição. Fazendo duas requisições POST idênticas o resultado mais comum será duas respostas iguais com a mesma informação mas ocasionalmente essa resposta pode mudar.


GET – READ/para selecionar/recuperar um recurso


O verbo HTTP GET é usado para ler ou recuperar uma representação de um recurso. Em um “cenário feliz”, uma requisição GET retorna uma representação em XML ou JSON e um HTTP status code 200 (OK). Em um cenário de erro o retorno mais comum é 404 (NOT FOUND) ou 400 (BAD REQUEST).
De acordo com o design da especificação HTTP, o verbo GET (juntamente com o HEAD) é usado apenas para ler informações e não para alterá-la. Portanto quando usado dessa maneira é considerado seguro. Ou seja, ou seja eles podem ser invocados sem risco de perda ou corrupção de dados — chamando uma vez tem o mesmo efeito de chamá-lo 10 vezes, ou nenhuma. Além disso, o verbo GET (e HEAD) é idempotente, o que significa que se fizermos múltiplas requisições teremos sempre o mesmo resultado.
Você nunca deveria expor operações inseguras via GET — ele nunca deve ser usado para modificar informações no servidor.


PUT – UPDATE/para modificar um recurso


O verbo PUT é comumente usado para atualizar informações, colocando um recurso conhecido no (body) corpo da requisição contendo novas informações que representam o recurso original.
Entretanto, o verbo PUT também pode ser usado para criar um recurso caso o ID do mesmo seja definido pelo cliente ao invés do servidor. Em outras palavras se o verbo PUT é proveniente de uma URI que não contenha um recurso com um ID preexistente. Nesse caso o corpo da requisição contém a representação de um recurso. Para muitos isso pode parecer complicado e confuso. Conseqüentemente, este verbo deve ser usado com moderação para a criação de um novo recurso.
Uma alternativa para isso é utilizar o verbo POST para criar novos recursos com o ID definido pelo cliente setado no corpo da requisição — caso não tenha o ID definido para o recurso deve-se usar o verbo POST(confira acima).
Um update bem sucedido, retorna um status code 200 (ou 204 quando não retorna nenhum conteúdo no body. Se estiver usando o verbo PUT para criar um novo recurso, o retorno deve ser um status code 201 em caso de uma criação bem sucedida. O response body é opcional — lembrando que quando ele é exposto há um consumo maior de banda. Caso o cliente seja o responsável por definir o ID do recurso não é necessário retornar um link para o mesmo via location header.
O verbo PUT não é uma operação segura, na medida em que modifica(ou cria) um recurso no servidor, mas ele é idempotente. Em outras palavras, se você cria ou atualiza um recurso usando o verbo PUT e executa a mesma operação de novo, o recurso terá o mesmo estado que na primeira execução.
Se, por exemplo, você fizer uma requisição PUT para um recurso que incrementa um contador dentro de um recurso, a requisição perde o comportamento de idempotente. As vezes isso acontece sendo suficiente apenas documentar a requisição como não idempotente. Entretanto, o recomendado para requisições PUT é implementar apenas requisições idempotentes. Sendo assim é fortemente recomendado o uso do verbo POST para operações não idempotentes.


DELETE – DELETE/para remover um recurso


O verbo DELETE é fácil de entender, ele é usado para deletar um recurso identificado por uma URI.
Em uma deleção bem sucedida retorna-se um status code 200 (OK) juntamente com um response body, possivelmente uma representação do item deletado (o que acaba por demandar muita banda), ou uma response customizada. Ou retornar o status code 204 (NO CONTENT) sem response body. Em outras palavras, um status code 204 sem corpo, ou JSEND-style response com um status code 200 são as responses mais recomendadas.
As operações de DELETE são idempotentes. Se você deleta um recurso, ele é removido sendo impossível repetir a operação uma vez que o recurso não existe mais. Se você utilizar o verbo DELETE para decrementar um contador (dentro de um recurso), sua operação DELETE não será mais idempotente. Como dito anteriormente, estatísticas de uso e métricas podem ser atualizadas enquanto o serviço é considerado idempotente e as informações do recursos permanecem inalteradas. É recomendado o uso do verbo POST para operações não idempotentes.
Existe uma recomendação quanto a idempotência do DELETE entretanto repetir uma requisição de DELETE em um recurso, normalmente, retorna um status code 404 (NOT FOUND) uma vez que já foi removido e, portanto, não existe mais. Para muitos uma operação de DELETE não é idempotente, entretanto, o resultado final do recurso é o mesmo. Retornar um status code 404 é aceitável e comunica com precisão o status da requisição.


Como podemos perceber, esses quatro verbos nos permite traçar uma certa analogia entre os verbos HTTP e o SQL. Observando a tabela abaixo isto fica um pouco mais claro.


image2


Além dos verbos mencionados anteriormente temos outros menos usados.


HEAD – O verbo HEAD possui uma funcionalidade similar ao verbo GET, exceto pelo fato do servidor retornar uma response line e headers, mas sem um entity-body.
TRACE – O verbo TRACE é usado para recuperar o conteúdo de uma requisição HTTP de volta podendo ser usado com o propósito de debug durante o processo de desenvolvimento.
OPTIONS – O verbo OPTIONS é usado pelo cliente para encontrar operações HTTP e outras opções suportadas pelo servidor. O cliente pode especificar uma URL para o verbo OPTIONS ou um asterisco (*) para se referir a todo o servidor.
CONNECT – O verbo CONNECT é usado pelo cliente para estabelecer uma conexão de rede com um servidor via HTTP.
PATCH – O verbo PATCH pode ser usado para realizar updates parcias de um recurso. Por exemplo, quando você precisar alterar apenas um campo em um recurso, executar um POST com todo o objeto é pesado e acarreta em um maior consumo de banda. Levando isso em conta a primeira coisa que vem em mente é: “por que não usar o PATCH ao invés do PUT para realisar atualizações sempre?”. Simples o verbo PATCH pode ser um problema na medida em que não é idempotente. Além disso minimizar seu uso previne curupção de dados por “colisões” entre duas PATCH requests no mesmo recurso em um mesmo frame de tempo. Colisões entre multiplas PATCH requests são mais perigosas que colisõs entre PUT requests por que exige que o cliente tenha informações básicas do recurso ou irão corrompê-lo.


Formatos Suportados em Web Services RESTful


● XML
● JSON
● CSV
● Texto
● Imagens
● HTML
● PDF
● binário
● etc


Vantagens dos Web Services RESTful


REST é um padrão arquitetural basicamente leve por natureza. Então quando você tiver limitações de banda prefira web services REST;
● Desenvolvimento fácil e rápido;
● Grandes sites como Twitter, Yahoo, Google, Facebook usam este padrão.
● Aplicativos Mobile tem ganhado cada vez mais espaço e precisam interagir rapidamente com os servidores e o padrão REST é mais rápido no processamento de dados das requests e responses.


Botando em prática


Em breve estarão disponíveis dois posts Criando o primeiro endpoint REST com SpringBoot e Documentando aplicações RESTfull com SpringBoot e Swagger com exemplos práticos.


Referências


Apache CXF
JBoss RestEasy
Jersey
Redhat
Elkstein
DZone
REST API Tutorial
The RESTful CookBook
Tutorials Point

Tags: , , , ,