Arquivo por categoria REST

Criando o primeiro endpoint REST com SpringBoot



Neste post daremos continuidade a uma série de postagens sobre Web-Services divididos entre conceitos teóricos e praticos. Nos 3 primeiros posts focou-se em teoria com um sobre Web Services, outro sobre RESTful Web Services e mais um sobre os HTTP Status Codes mais comuns. Este post por sua vez complementa o que foi desenvolvido no post Do zero ao REST em 5 minutos com SpringBoot. Então antes de começar veja o post anterior ou baixe o código e vamos entender na prática como funcionam os verbos REST.



Agora faremos algumas alterações no projeto desenvolvido no post anterior. Para começar crie os seguintes pacotes br.com.erudio.models, br.com.erudio.services, br.com.erudio.services.implementations e br.com.erudio.web.controllers. Depois mova a classe Greeting para o pacote br.com.erudio.models e a classe GreetingController para o pacote br.com.erudio.web.controllers. A estrutura de pacotes deve ficar similar a imagem abaixo.

postagem_2_0



Feito isto crie uma classe chamada Person, no pacote br.com.erudio.models, com as informações que serão representadas pelo nosso endpoint REST.

package br.com.erudio.models;

import java.io.Serializable;

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;

@JsonIgnoreProperties(ignoreUnknown = true)
public class Person implements Serializable{
    
    private static final long serialVersionUID = 1L;
    
    private Long id;
    private String firstName;
    private String lastName;
    private String address;
    
    public Long getId() {
        return id;
    }
    
    public void setId(Long id) {
        this.id = id;
    }
    
    public String getFirstName() {
        return firstName;
    }
    
    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }
    
    public String getLastName() {
        return lastName;
    }
    
    public void setLastName(String lastName) {
        this.lastName = lastName;
    }
    
    public String getAddress() {
        return address;
    }
    
    public void setAddress(String address) {
        this.address = address;
    }
}


Feito isto crie uma interface com o nome PersonService no pacote br.com.erudio.models.


package br.com.erudio.services;

import java.util.List;

import br.com.erudio.models.Person;

public interface PersonService {
    
    Person create(final Person person);
    Person findById(final String personId);
    List<Person> findAll();
    Person update(Person person);
    void delete(final String personId);

}



Agora vamos criar a implementação para a interface PersonService. No pacote br.com.erudio.services.implementations crie a classe PersonServiceImpl que implementa a interface que acabamos de criar.

package br.com.erudio.services.implementations;

import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.atomic.AtomicLong;

import org.springframework.stereotype.Service;

import br.com.erudio.models.Person;
import br.com.erudio.services.PersonService;

@Service
public class PersonServiceImpl implements PersonService {
    
	// Contador responsável por gerar um fake ID já que não estamos
	// acessando nenhum banco de dados
    private final AtomicLong counter = new AtomicLong();

	// Metodo responsável por criar uma nova pessoa
	// Se tivéssemos um banco de dados esse seria o
	// momento de persistir os dados
    @Override
    public Person create(Person person) {
        return person;
    }

	// Método responsável por retornar uma pessoa
	// como não acessamos nenhuma base de dados
	// estamos retornando um mock
    @Override
    public Person findById(String personId) {
        Person person = new Person();
        person.setId(counter.incrementAndGet());
        person.setFirstName("Leandro");
        person.setLastName("Costa");
        person.setAddress("Uberlândia - Minas Gerais - Brasil");
        return person;
    }

	// Método responsável por retornar todas as pessoas
	// mais uma vez essas informações são mocks
    @Override
    public List<Person> findAll() {
        ArrayList<Person> persons = new ArrayList<>();
        for (int i = 0; i < 8; i++) {
            Person person = mockPerson(i);
            persons.add(person);
        }
        return persons;
    }
    
	// Método responsável por atualizar uma pessoa
	// por ser mock retornamos a mesma informação passada
    @Override
    public Person update(Person person) {
    	return person;
    }

	// Método responsável por deletar
	// uma pessoa a partir de um ID
    @Override
    public void delete(String personId) {

    }
		
	// Método responsável por mockar uma pessoa
    private Person mockPerson(int i) {
        Person person = new Person();
        person.setId(counter.incrementAndGet());
        person.setFirstName("Person Name " + i);
        person.setLastName("Last Name " + i);
        person.setAddress("Some Address in Brasil " + i);
        return person;
    }
}



Por fim crie a classe PersonController, responsável por expor o endpoint de pessoas, no pacote br.com.erudio.web.controllers.

package br.com.erudio.web.controllers;

import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;

import br.com.erudio.models.Person;
import br.com.erudio.services.PersonService;

@RestController
//Mapeia as requisições de localhost:8080/person/
@RequestMapping("/person/")
public class PersonController {
    
    @Autowired
    private PersonService personService;
    
    @ResponseStatus(HttpStatus.OK) //Por padrão responde com o status code 200 success
    @RequestMapping(value = "/{personId}",
		//Mapeia as requisições GET para localhost:8080/person/
		//recebendo um ID como @PathVariable
		method = RequestMethod.GET, 
		produces = MediaType.APPLICATION_JSON_VALUE)
		// Produz JSON como retorno
    public Person get(@PathVariable(value = "personId") String personId){
        return personService.findById(personId);
    }
    
    @ResponseStatus(HttpStatus.OK)
	//Por padrão responde com o status code 200 success
    @RequestMapping(value = "/findAll",
		//Mapeia as requisições GET para localhost:8080/person/findAll
		method = RequestMethod.GET,
		produces = MediaType.APPLICATION_JSON_VALUE)
		// Produz JSON como retorno
    public List<Person> findAll(){
        return personService.findAll();
    }
    
    @ResponseStatus(HttpStatus.OK)
	//Por padrão responde com o status code 200 success
    @RequestMapping(method = RequestMethod.PUT,
	//Mapeia as requisições PUT para localhost:8080/person/
		consumes = MediaType.APPLICATION_JSON_VALUE,
		// Consome JSON enviado no corpo da requisição
		produces = MediaType.APPLICATION_JSON_VALUE)
		// Produz JSON como retorno
    public Person create(@RequestBody Person person){
        return personService.create(person);
    }
    
    @ResponseStatus(HttpStatus.OK)
	//Por padrão responde com o status code 200 success
    @RequestMapping(method = RequestMethod.POST,
	//Mapeia as requisições POST para localhost:8080/person/
		consumes = MediaType.APPLICATION_JSON_VALUE)
		// Consome JSON enviado no corpo da requisição
    public Person update(@RequestBody Person person){
        return personService.update(person);
    }

    @ResponseStatus(HttpStatus.OK)
	//Por padrão responde com o status code 200 success
    @RequestMapping(value = "/{personId}",
		method = RequestMethod.DELETE)
		//Mapeia as requisições DELETE para localhost:8080/person/ 
		//recebendo um ID como @PathVariable
    public void delete(@PathVariable(value = "personId") String personId){
        personService.delete(personId);
    }
}



Agora que terminamos nossa codificação acesse a classe Application e inicie a aplicação como no post anterior. Para testar nosso endpoint e cada uma de suas operações usaremos o plugin do Chrome Postman.


Primeiro faremos uma requisição do tipo GET chamando a operação findAll para o recurso localhost:8080/person/findAll. Como se pode ver na imagem abaixo obtemos como resposta um JSON com um array de pessoas.

postagem_2_2



Agora faremos uma requisição do tipo GET chamando a operação localhost:8080/person/1 passando como @PathVariable o ID da pessoa que desejamos recuperar. Da mesma forma que na requisição anterior recebemos como resposta um JSON com 1 objeto pessoa.

postagem_2_1

Agora faremos uma requisição do tipo POST (esse é o verbo REST usado para persistir informações) chamando a operação localhost:8080/person/ passando como parâmetro um JSON com um objeto pessoa no corpo da requisição. Para isso no Postman precisamos setar o tipo de requisição como POST, na aba Body definimos o JSON que representa o objeto pessoa a ser gravado, selecionamos a opção raw, definimos a opção JSON(application/json) e por fim executamos a request através do botão send.

postagem_2_3

Na imagem abaixo podemos ver o body da response retornada com um ID definido pela aplicação.


postagem_2_4

Agora faremos uma requisição do tipo PUT (esse é o verbo REST usado para atualizar informações) chamando a operação localhost:8080/person/ passando como parâmetro um JSON com um objeto pessoa no corpo da requisição. Lembrando que essa representação de pessoa deve ter um ID que será usado pra localizar e atualizar um recurso na base. Para isso no Postman precisamos setar informações similares ao post a unica diferença é que o tipo de requisição deve ser o PUT.



postagem_2_5

Como se pode ver na imagem abaixo o body da response retorna o nosso objeto JSON com as alterações.

postagem_2_6



Por fim faremos uma requisição do tipo DELETE (verbo REST usado excluir informações) chamando a operação localhost:8080/person/1 passando como @PathVariable o ID da pessoa que desejamos remover da base. Esse tipo de requisição retorna como resposta um body vazio e um StatusCode 200 caso a operação seja executada com sucesso os StatusCode 204 (no content), 401 (Unauthorized), 403 (forbiden), 404 (not found) ou 500 (internal server error) podem ser retornados.


postagem_2_7


Dessa forma abordamos os 4 verbos principais do HTTP usados em aplicações REST. Lembrando que você pode baixar o código aqui e descompactar o arquivo zip e importar não sua IDE de preferencia ou clonar usando Git:

git clone https://github.com/leandrocgsi/simple-rest-example-verbs.git



Continue ligado no blog, por que no próximo post iremos documentar a nossa API com o framewrok Swagger. E claro a abordagem nesses posts também será totalmente mão na massa. É isso aí bons estudos.

Tags: , , , ,

Do zero ao REST em 5 minutos com SpringBoot



Este post visa explicar de forma simples como criar um “hello world” RESTFul web service com Spring Boot.



Fique ligado no blog, por que, como já foi dito, nos próximos 2 posts entraremos em maiores detalhes sobre a sopa de letrinhas dos verbos REST, POST, PUT, GET e DELETE na prática e depois documentaremos a nossa API com o framewrok Swagger. E abordagem nesses posts será totalmente mão na massa. É isso aí bons estudos.

Cerca de 5 minutos
Qualquer IDE de preferência o Eclipse
JDK 1.8 ou superior
Maven 3.33+



Onde baixar os códigos do projeto

Você pode baixar o código aqui e descompactar o arquivo zip e importar não sua IDE de preferencia ou clonar usando Git:

git clone https://github.com/leandrocgsi/simple-rest-example.git



Para mais detalhes e para evoluir este projeto acesse a página de guias de inicialização da fundação Spring. Além disso serão feitos mais 2 posts fechando uma série sobre Spring Boot e RESTful abordando os 4 principais verbos REST e como documentar API’s com o framework Swagger. O código dos próximos posts já está implementado e você pode acessar o de verbos aqui e o com Swagger aqui.



E a teoria como fica?


Se você está lendo este post eu acredito que você conheça o mínimo de teoria sobre REST e Web-Services mas se não conhece temos 3 posts que abordam esses temas de forma teórica sendo um sobre Web Services, outro sobre RESTful Web Services e outro sobre os HTTP Status Codes em Serviços REST mais comuns.

Hora de codar



Então chega de conversa e vamos botar a mão na massa ou melhor no código. Com o Eclipse aberto clique em novo escolha a opção Maven Project como na imagem abaixo.

1



Na próxima janela selecione a opção “Create a simple project(skyp archetype selection)”. Isso “diz” ao Maven que você irá construir seu projeto do zero com uma estrutura padrão Maven mas sem usar nenhum Archetype pronto.

2



Na próxima tela defina o Goup Id do seu projeto, no nosso caso “br.com.erudio”. Defina também o Artifact Id (nome) do seu projeto e a versão. Feito isto clique em next.

3



Se tudo tiver corrido bem você terá um projeto com uma estrutura similar à imagem abaixo. Abra o arquivo “pom.xml” e vamos fazer algumas alterações nele.

4



A estrutura original do pom deve ser algo similar a esta:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    
    <groupId>br.com.erudio</groupId>
    <artifactId>simple-rest-example</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    
</project>



Primeiro informamos o “parentesco” do nosso projeto em relação ao Spring boot. Logo abaixo adicionamos a dependência do Spring Boot Starter Web que como o próprio nome diz é o responsável por inicializar nossa aplicação. Definimos também a versão do Java no nosso caso 1.8. Depois precisamos configurar o processo de build que é extremamente simples. E por fim adicionamos os repositórios de onde o Maven irá baixar as dependências e plug-ins necessários ao projeto. Feito isso nos já temos a estrutura básica de um projeto Spring Boot.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    
    <groupId>br.com.erudio</groupId>
    <artifactId>simple-rest-example</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    
    <!-- Adicionando o Spring Boot ao projeto -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.3.3.RELEASE</version>
    </parent>
    
    <!-- Adicionando a dependencia do Spring Boot Starter Web -->
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    </dependencies>

    <!-- Configurando a versão do Java -->
    <properties>
        <java.version>1.8</java.version>
    </properties>
    
    <!-- Configurando o processo de build da aplicação -->
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
    
    <!-- Adicionando o repositório do Spring de onde o Maven irá baixar as dependências -->
    <repositories>
        <repository>
            <id>spring-releases</id>
            <url>https://repo.spring.io/libs-release</url>
        </repository>
    </repositories>
    
    <!-- Adicionando o repositório do Spring de onde o Maven irá baixar os plugins -->
    <pluginRepositories>
        <pluginRepository>
            <id>spring-releases</id>
            <url>https://repo.spring.io/libs-release</url>
        </pluginRepository>
    </pluginRepositories>
    
</project>



Como se pode ver o nosso projeto está com um marker de erro e a versão do Java está como 1.5 e não 1.8 como definimos no pom.xml.

7



Clique com o direito sobre o projeto escola a opção Build Path >> Configure Build Path

8



Na aba libraries selecione sua JRE System Library e clique em editar.

9



Na proxima janela selecione o radio Alternate JRE e escolha sua versão do Java e clique em Finish.

10



Como se pode ver agora a versão esta correta, então clique em OK.

11



Além disso temos um Mavem problem etratanto isso é apenas um bug do Eclipse e apesar do warning o projeto executa normalmente. Para remover basta escolher a opção quick fix.

12



Na janela a seguir escolha a opção Update project configuration clique em Finish e adeus warning.

13



Agora que eliminamos todos os warnings o ambiente está pronto. Selecione o source folder src/main/java.

14



Clique com o direito New >> Package

15



Na próxima janela defina o nome do pacote no nosso caso “br.com.erudio”.

16



Feito isso abra o souce folder e clicando sobre o pacote com o botão direito New >> Class

17



Na próxima janela defina o nome Greeting(Saudação em inglês já que é um Hello World) e insira o código abaixo. Como você pode perceber é um simples POJO que representa o objeto que será retornado aos clientes de nossa API.


package br.com.erudio;

public class Greeting {

    private final long id;
    private final String content;

    public Greeting(long id, String content) {
        this.id = id;
        this.content = content;
    }

    public long getId() {
        return id;
    }

    public String getContent() {
        return content;
    }
}



Agora crie uma nova classe com o nome GreetingController que é o nosso endpoit que receberá as requisições REST. Como se pode ver as requisições para a url {{contexto}}/greeting invocarão o método greeting que recebe um @RequestParam com um nome. Quando esse valor não é informado o valor padrão é “World”. As requisições para esse endpoint retornam uma saudação com um id automático simulando um acesso a um banco de dados e uma string com a saudação.


package br.com.erudio;

import java.util.concurrent.atomic.AtomicLong;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class GreetingController {

    private static final String template = "Hello, %s!";
    private final AtomicLong counter = new AtomicLong();

    @RequestMapping("/greeting")
    public Greeting greeting(@RequestParam(value="name", defaultValue="World") String name) {
        return new Greeting(counter.incrementAndGet(), String.format(template, name));
    }
}



Agora vamos definir a classe de inicialização de nossa aplicação chamada Application. Acredite ou não com apenas o trecho de código abaixo você tem sua aplicação pronta sem necessidade de container ou server. Sim o Spring Boot te liberta de Tomcat, Jetty ou os “obesos” JBoss e GlassFish e seus EJB’s.


package br.com.erudio;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}



Com a aplicação pronta clique com o direito dobre a classe Application Run As >> Java Application. Caso você esteja usando a Spring Source Tool Suite (ferramenta baseada no Eclipse com foco em desenvolvimento Spring) como é o meu caso pode excolher a opção Spring Boot App.

18



Se você tiver feito tudo corretamente terá um console parecido com a imagem abaixo observe que o endpoint /greeting foi mapeado e que nossa aplicação iniciou em apenas 4 segundos.

19



Vá no browser de sua preferencia e acesse localhost:8080/greeting e terá uma resposta parecida com a imagem abaixo.

20



Agora adicione um parametro a mais a nossa url localhost:8080/greeting?name=Olá Semeru Blog ou outro parametro de sua preferência e terá uma resposta similar à imagem abaixo.

21



Fique ligado no blog, por que, como já foi dito, nos próximos 2 posts entraremos em maiores detalhes sobre a sopa de letrinhas dos verbos REST, POST, PUT, GET e DELETE na prática e depois documentaremos a nossa API com o framewrok Swagger. E abordagem nesses posts será totalmente mão na massa. É isso aí bons estudos.

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: , , , ,

Web Services

Nos últimos meses me pediram a definição de Web-services em 3 processos seletivos diferentes, por mais simples que possa parecer definir conceitualmente pode ser mais complexo do que parece, sendo assim decidi fazer uma série de posts a respeito. Neles iremos aprender sobre os diferentes tipos de Web Services – ou simplesmente serviços. Pra começo de conversa um Serviço nada mais é que uma aplicação interoperável hospedada e acessada através da web através do protocolo HTTP por meio de um browser ou de diferentes tipos de clientes, como outras aplicações ou serviços. Deixando um pouco mais claro quando você cria um website em PHP a saída padrão é HTML e seu alvo é o browser e por extensão nós podemos visualizar a página no browser. Um web service não é direcionado para humanos e sim para outros programas.
O World Wide Web Consortium (W3C) define os web services como: aplicações cliente servidor que se comunicam pela World Wide Web’s (WWW) através do protocolo HTTP (HyperText Transfer Protocol) possibilitando a interoperabilidade entre softwares e aplicações executando em uma grande variedade de plataformas e frameworks. Caracterizam-se por sua grande interoperabilidade e extensibilidade podendo ser combinados de forma baixamente acoplada para executarem operações complexas. Programas proveem simples serviços que podem interagir uns com os outros gerando soluções sofisticadas.

Os serviços podem ser divididos em 2 grupos mais comumente conhecidos e usados, são eles:
eles:


REST (Representational State Transfer)


SOAP (Simple Object Access Protocol)


REST


JAX-RS 2.0 especificação que suporta a implementação para os serviços baseados RESTful no mundo Java.
● As principais implementações disponíveis para essa essa especificação são: Apache CXF, Spring MVC, JBoss RestEasy, Oracle Jersey (2.x) e Glassfish Jersey (2.x).


SOAP


JAX-WS 2.0 especificação que suporta a implementação para os serviços baseados em SOAP no mundo Java.
● As principais implementações disponíveis para essa essa especificação são: Apache CXF, JAX-WS, Apache Axis2 e Oracle WebLogic.


O diagrama abaixo representa bem essa “divisão” entre os 2 principais tipos de serviços.


image1


Nos próximos posts entraremos em maiores detalhes sobre a sopa de letrinhas REST, SOAP, SOA, API etc. Além disso iremos botar a mão na massa e codar um pouco.


Referências:


https://docs.oracle.com/javaee/6/tutorial/doc/gijvh.html

http://www.w3schools.com/webservices/ws_intro.asp

http://www.tutorialspoint.com/webservices/what_are_web_services.htm

http://stackoverflow.com/questions/226108/what-is-a-web-service-in-plain-english

Tags: , , , ,

Resolvendo problemas de configuração do SpringMVC

Salve, salve pessoal se você está trabalhando com Spring MVC e se deparou com a exception org.springframework.web.HttpMediaTypeNotAcceptableException: Could not find acceptable representation este artigo visa ajudar a resolver este problema.
Isso se deve ao fato do HttpMessageConverter não estar configurado ou configurado com erros. A solução é editar sua classe de configurações WebMvcConfig adicionando dois converters ResourceHttpMessageConverter e MappingJackson2HttpMessageConverter. Isso é bastante simples e basta que você adicione o trecho de código abaixo:


    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
    	converters.add(converterResourceHttpMessageConverter());
        converters.add(converterJackson2Http());
        super.configureMessageConverters(converters);
    }
    
    @Bean
    public MappingJackson2HttpMessageConverter converterJackson2Http() {
    	MappingJackson2HttpMessageConverter converter = new MappingJackson2HttpMessageConverter();
    	//do your customizations here...
    	return converter;
    }
    
    @Bean
    public ResourceHttpMessageConverter converterResourceHttpMessageConverter() {
    	ResourceHttpMessageConverter converter = new ResourceHttpMessageConverter();
    	//do your customizations here...
    	return converter;
    }

Bom mas pode ser que você se depare ainda com a exception java.lang.ClassNotFoundException: org.codehaus.jackson.JsonProcessingException. E a solução também é simples, certifique se de que as dependências jackson-core-asl, jackson-mapper-asl e jackson-jaxrs-xml-provider estejam adicionadas ao projeto, caso não estejam adicionem. Para quem usa Maven eu vou facilitar ainda mais as coisas, basta adicionar esse trecho de código ao seu pom.xml e ser feliz, para os demais é só sair catando jar na pata.


	<dependency>
		<groupId>org.codehaus.jackson</groupId>
		<artifactId>jackson-core-asl</artifactId>
		<version>XYZ</version>
	</dependency>
	<dependency>
		<groupId>org.codehaus.jackson</groupId>
		<artifactId>jackson-mapper-asl</artifactId>
		<version>XYZ</version>
	</dependency>
	<dependency>
		<groupId>com.fasterxml.jackson.jaxrs</groupId>
		<artifactId>jackson-jaxrs-xml-provider</artifactId>
		<version>XYZ</version>
	</dependency>

Feito isto é só inicializar novamente o projeto que as coisas irão funcionar.

Tags: , , ,