Expondo um Serviço Rest no OSB – Parte 1: Criando uma API Rest

A ideia deste Post será mostrar como podemos expor no OSB um Serviço Rest, por isso nesta primeira parte vamos criar uma pequena API Rest usando o SpringBoot do JAVA.

Mas o que é uma API ?

Application Programming Interface (Em português, significa Interface de Programação de Aplicações), trata-se de um conjunto de rotinas e padrões estabelecidos e documentados por uma aplicação A, para que outras aplicações consigam utilizar as funcionalidades desta aplicação A, sem precisar conhecer detalhes da implementação do software.

E o que é Rest ?
Representational State Transfer (Em português, significa Transferência de Estado Representacional. basicamente o REST consiste em princípios/regras/constraints que, quando seguidas, permitem a criação de um projeto com interfaces bem definidas. Desta forma, permitindo, por exemplo, que aplicações se comuniquem.

E qual a diferença entre Rest e RESTful ?
A diferença é apenas gramatical. Em outras palavras, sistemas que utilizam os princípios REST são chamados de RESTful.
Rest: Conjunto de princípios de arquitetura
RESTful: Capacidade de determinado sistema aplicar os principios de REST

A exposição do serviço Rest no OSB será dividida em Partes conforme abaixo para que eu consiga detalhar ao máximo cada etapa, consulte o Link de cada uma para ver as demais Partes:

• Parte 1: Criando uma API Rest Parte 1: Criando uma API Rest
• Parte 2: Transformando Xml em Json Java
• Parte 3: Criando o Projeto no OSB
• Parte 4: Expondo o Proxy usando Java Callout

A ideia do Post não é explicar como o Spring Boot funciona e nem suas anotações, mas tentarei ao máximo explicar ao menos o que estou usando que nesta primeira etapa será criar apenas um HelloWorld pois será o suficiente para entendermos e implantarmos qualquer API Rest

No Site https://start.spring.io vamos criar um projeto SpringBoot conforme abaixo

Veja abaixo que selecionamos apenas as Dependencias “Web” que é o padrão para criarmos o projeto e “DevTools” para que possamos fazer alterações no código sem ter que ficarmos reiniciando nosso TomCat.

Em Name e Artifact coloque helloworld e em Package Name coloquei br.com.uanscarvalho.helloworld conforme abaixo:

Após isso clique no botão Generate Project conforme abaixo para criarmos nosso projeto

Logo após salve o projeto em uma pasta de sua preferencia:

Agora extraia o arquivo na sua workspace, veja abaixo onde o meu projeto ficou:

Agora vamos importar este projeto no Eclipse. No meu caso vou utilizar o Eclipse Spring Tool Suite.

No eclipse basta apenas clicar em File –> import –> import e na tela abaixo clique em Maven –> Existing Maven Projects

Veja abaixo como ficou o meu projeto após ser importado:

Veja abaixo como esta o pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<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>
   <parent>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-parent</artifactId>
      <version>2.1.2.RELEASE</version>
      <relativePath />
      <!-- lookup parent from repository -->
   </parent>
   <groupId>br.com.uans</groupId>
   <artifactId>helloworld</artifactId>
   <version>0.0.1-SNAPSHOT</version>
   <name>helloworld</name>
   <description>Demo project for Spring Boot</description>
   <properties>
      <java.version>1.8</java.version>
   </properties>
    <dependencies>
       <dependency>
  			<groupId>com.fasterxml.jackson.core</groupId>
  			<artifactId>jackson-databind</artifactId>
  			<version>2.8.5</version>
	  </dependency>
      <dependency>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-starter-web</artifactId>
      </dependency>
      <dependency>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-starter-test</artifactId>
         <scope>test</scope>
      </dependency>
      <dependency>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-devtools</artifactId>
         <scope>runtime</scope>
      </dependency>
   </dependencies>
   <build>
      <plugins>
         <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
         </plugin>
      </plugins>
   </build>
</project>

 

Agora no Eclipse faça os Clean e install necessários no Maven para que possam ser instaladas as dependências necessárias conforme nosso pom.xml

Veja abaixo que foi criado automaticamente a classe HelloworldApplication.java já com a anotação @SpringBootApplication

A anotação @SpringBootApplication é uma anotação de conveniência que contém as seguintes anotações do Spring: @Configuration, @EnableAutoConfiguration e @ComponentScan. Essas duas últimas, basicamente, dizem ao inicializador do Spring: “Busque e instancie todo bean anotado deste pacote para frente”.

 

Um pouco sobre as Anotações:

@Configuration: 
É uma annotation que indica que determinada classe possui métodos que expõe novos beans.

@EnableAutoConfiguration:
Utilizada pelo Spring Boot para tentar advinhar as configurações necessárias para rodar o seu projeto.@EnableAutoConfiguration, que talvez seja a mais importante desse pacote.Essa é uma outra annotation do Spring Boot que indica a necessidade da auto configuração do seu projeto. Por conta da existência dela que vai ser disparado o processo de análise das classes presentes no seu classpath para que várias das configurações que nos acostumamos a fazer sejam evitadas. Por exemplo, quando for achado os jars do Hibernate já vai ser configurado automaticamente um LocalEntityManagerFactoryBean para que seja possível criar EntityManager no seu projeto. Um outro exemplo é a configuração automática do servlet container embedded, quando você adiciona o starter do Tomcat no seu projeto.

@ComponentScan: 
Em geral você a usa em classes de configuração(@Configuration) indicando quais pacotes ou classes devem ser scaneadas pelo Spring para que essa configuração funcione

Agora no Eclipse crie a classe HelloworldController conforme abaixo

Dentro da Classe HelloworldController vamos ter o seguinte código:

package br.com.uanscarvalho.helloworld;

import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloworldController {

	
	@RequestMapping(value = "/", produces = MediaType.APPLICATION_JSON_VALUE, method = RequestMethod.GET)
	public String welcome(@RequestParam(value="nome", required=false) String nome) {
		return "Ola " + nome;
	}

}

Apenas para conteúdo veja abaixo uma outra forma de deixarmos nossa classe que no final teria o mesmo efeito, aqui mostro apenas uma das muitas formas de passarmos o parâmetro para o nosso método e para testes no final faríamos uma chamada no browser assim: http://localhost:9000/Uans

@RequestMapping(value = "/{nome}", produces = MediaType.APPLICATION_JSON_VALUE, method = RequestMethod.GET)

public String welcome(@PathVariable("nome") String nome) {
       return "Ola " + nome;
}

Entendendo um pouco do que foi feito, aqui lembro que minha intenção é apenas explicar o básico do que estamos fazendo já que existem diversas formas de fazer a mesma coisa.

@Controller: É usado para sinalizar que a classe é um MVC Controller do Spring.

@RestController: Esta anotação adiciona automaticamente a anotação @Controller e @ResponseBody e não faz nada além disso, e neste caso todo retorno do serviço será transformado para um JSON.

@RequestMapping: Utilizada em cima dos métodos de uma classe anotada com @Controller ou @RestController .

Veja abaixo alguns parâmetros que podemos usar nesta anotação RequestMapping

value = “/” Serve para você colocar os endereços da sua aplicação, no nosso caso por exemplo @RequestMapping(value = “/” ) que quando acessados por algum cliente, deverão ser direcionados para o determinado método (“/”), poderia ser qualquer nome, por exemplo (“/cliente”).

produces = MediaType.APPLICATION_JSON_VALUE Aqui estamos dizendo ao método que nosso retorno deverá ser um JSON.. caso quiséssemos que fosse um XML usaríamos APPLICATION_XML_VALUE
mas caso tenhamos que especificar que iremos passar um JSON como request então colaremos a opção consumes= MediaType.APPLICATION_JSON_VALUE

method = RequestMethod.GET aqui estamos dizendo ao método http deve ser um GET, caso este propriedade seja omitida o método passaria a atender a todos os métodos (GET, POST, PUT, DELETE, etc.)

(@RequestParam(value = “nome”, required = false) String nome) Aqui estou dizendo ao método que ele deve esperar como parâmetro um nome “nome” que deverá ser uma String, ou seja, ao acessar “/?nome=SeuNomeAqui” o parâmetro nome será atribuír a variável “nome”, e se o parâmetro não for passado, o que acontecerá? Será retornado um erro: “Required String parameter ‘nome’ is not presente”. Mas caso não queira que o parâmetro seja obrigatório, basta mapeá-lo como “@RequestParam(required = false)”, e veja como o nome recebe null, e nenhum erro será retornado. O uso dependerá de sua necessidade.

@ResponseBody Utilizada em métodos anotados com @RequestMapping para indicar que o retorno do método deve ser automaticamente escrito na resposta para o cliente. Muito comum quando queremos retornar JSON ou XML em função de algum objeto da aplicação.

Acima você viu que existem várias formas de criarmos um simples HelloWorld não é mesmo ? Porem para um caso um pouco mais real sugiro que você faça apartir da classe abaixo pois nela passaremos um parâmetro que é a forma mais comum onde as aplicações precisam de parâmetros a serem passados (na grande maioria dos casos).

Classe HelloworldController Principal:

Então crie a classe conforme abaixo:

package br.com.uanscarvalho.controller;

import org.springframework.http.MediaType;
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.ResponseBody;
import org.springframework.web.bind.annotation.RestController;

import br.com.uanscarvalho.bean.Pessoa;
import br.com.uanscarvalho.bean.Response;

@RestController
public class HelloworldController {

	@RequestMapping(value = "/hello", produces = MediaType.APPLICATION_JSON_VALUE, method = RequestMethod.POST)
	public @ResponseBody Response welcome(@RequestBody Pessoa pessoa) {

		Response response = new Response();
		response.setMensagem("Ola " + pessoa.getNome());

		return response;
	}
}

Sem entrar muito ainda em detalhes o que adicionamos aqui é a anotação @RequestBody onde o Spring tentará converter seu valor de retorno e gravá-lo na resposta http automaticamente e o @ResponseBody que usamos quando queremos retornar um JSON. Também criamos um Bean chamado Pessoa que irá conter o valor que passaremos para o Body e outro Bean chamado Response que irá conter nossa resposta da aplicação.

Agora no Eclipse crie a package br.com.uanscarvalho.bean e a classe Pessoa conforme abaixo

Agora dentro do Bean Pessoa adicione o seguinte codigo:

package br.com.uanscarvalho.bean;

public class Pessoa {

	private String nome;

	public String getNome() {
		return nome;
	}

	public void setNome(String nome) {
		this.nome = nome;
	}
	
}

Agora crie a classe Response conforme abaixo

Agora dentro do Bean Response adicione o seguinte codigo:

package br.com.uanscarvalho.bean;

public class Response {
	
	private String mensagem;

	public String getMensagem() {
		return mensagem;
	}

	public void setMensagem(String mensagem) {
		this.mensagem = mensagem;
	}

}

Vamos testar agora nossa aplicação:

Para isso execute o arquivo HelloworldApplication clicando com o botaão direito em cima da classe depois em Run As –> Spring Boot App
Obs: Caso você receba um erro dizendo Address already in use basta ir no arquivo application.properties e colocar “server.port=9000” para mudar a sua porta por exemplo para a porta 9000 ou o que voce quiser conforme exemplo abaixo

Agora o resultado deverá ser semelhante a este… veja na guia Console:

Agora vamos testar nossa simples aplicação

Para testar vou utilizar o Postman conforme abaixo mas fique a vontade para usar o que preferir, como o SOAPUI por exemplo:

Configure então para que chame a URL http://localhost:9000/hello e então adicione o seguinte Request no formato Json

{
	"nome": "Uans"
}

Veja abaixo como ficou toda a configuração, o Request e o Response no formato Json após termos chamado nossa aplicação

Abaixo o link para encontrar o codigo pronto direto no GitHub

https://github.com/uanscarvalho/HelloWorldSpringBoot.git

Obs: Uma dica do Git é apenas ir em algum local onde quer abrir o arquivo na sua maquina e usar o comando abaixo para baixar o projeto e em seguida basta abrir o eclipse e importar um projeto Maven e procurar o projeto para abrir.

git clone https://github.com/uanscarvalho/HelloWorldSpringBoot.git helloworld

Abraços e até a Próxima

/:-D