RESTful web services: When to use HTTP PATCH method


HTTP is a very interesting method but just a few application, SOA or Enterprise Integration developers use all of its capabitities. POST and GET among all HTTP Methods are the most used Method followed by PUT. Yet not very used the PATCH method is very useful and it plays a so specific role that it worth understanding its semantics.

In order to better understand HTTP’s PATCH method let’s have a real-world inspired example. The following figure is a simplified version of a integration project that I’ve been working on.

Users  connect to the cloud-based Payroll System in order to do many activivies such as employee data management.  This system holds the “master data” for employees.

Now imagine everytime an employee data is created or edited in the Payroll System we have to send this new/edited data  (the “1” in the figure) to other systems such as a Sales/Remuneration system (the “2” in the figure), a Performance Appraisal System (the “3” in the figure) and so on (the “4” in the figure).

As described in one of my last posts When to use HTTP Post and HTTP PUT, both POST and PUT create or edit a full Resource Representation, i.e., when you have all of its data.

Bringing it to our Payroll example it means we would create a RESTful web service – in our Tibco ESB – based on POST/PUT  method if the Payroll would send not only the edited Employee data but all its data (all attributes). But that was not the case of the Payroll system I was integrating with. The Payroll sends only the edited data, I mean, if a employee move to another apartment in the same building the payroll would send just the Address’ complement without the street name, city, postal code and so on so forth. That’s why HTTP PATCH was created for!

While in a PUT/POST request, the enclosed entity is considered to be a modified version of the resource stored on the
origin server, and the client is requesting that the stored version be replaced. With PATCH, however, the enclosed entity contains a set of instructions describing how a resource currently residing on the origin server should be modified to produce a new version.

Therefore, the final result of the RESTful web services created in Tibco ESB for this project was:

  • POST /employee/id:  Creates a employee in the Payroll system;
  • PUT /employee/id: Broadcasts a message  so that all other systems replace a full employee data. Actually, this will only be used in the future in my project and we did not created it;
  • PATCH /employee/id: Broadcasts a message  so that all other systems update just a set of a employee’s data.

That’s all for today. I hope you now are able to make a better decision on when to use POST, PUT and PATCH when designing RESTful web services.

Tchau!

Anúncios

WS-BPEL e os cabeçalhos HTTP de resposta


Nos últimos dias realizamos alguns testes com o GlassFish ESB expondo processos BPEL através de WebServices SOAP de diferentes maneiras. Tais testes foram feitos com dois diferentes padrões de troca de mensagens (MEP – Message Exchange Patterns): Request Only (Também conhecido como InOnly) e Resquest-Response.

Para quem não sabe, o GlassFish ESB possui um componente JBI chamado BPEL Service Engine que é implementação do padrão WS-BPEL. Relembre o que é o padrão JBI.

O motivo de ter feito esses testes é porque no caso dos serviços assíncronos eu estava pensando que, para o cliente saber se a requisição foi aceita pelo provedor do serviço bastaria verificar se cabeçalho HTTP de resposta era o 200 OK. Acontece que não é bem assim que a coisa funciona. Segue abaixo as constatações…

Serviços Resquest Only (São os serviços que estou considerando como sendo Assíncronos)

  • O GlassFish ESB, mais especificamente o BPEL SEsempre (eu disse SEMPRE) retorna o status HTTP/1.1 202 Accepted
    • Esse código indica que “…a requisição do cliente não pode ou não será tratada em tempo real, sendo processada mais tarde. A requisição parece válida, mas pode causar problemas quando for processada. Essa é uma resposta adequada quando uma requisição ativar uma ação assíncrona.“. Fonte:http://goo.gl/QEYZ
    • Nesse caso, o provedor do serviço não envia nenhum conteúdo no corpo da mensagem de resposta, ou seja, existe uma resposta mas ela é vazia no sentido que só existe o cabeçalho HTTP de resposta. Isso acontece dessa forma mesmo se o dentro da implementação do serviço (no nosso caso dentro de um BPEL) for gerada uma exception!!! Nesse caso temos que ter muita atenção ao tratamento de erros dentro do BPEL para não deixar a requisição “se perder”. Por exemplo, eu forcei a geração de uma exception dentro do processo e, mesmo usando um Throw ou fazendo uma conta de 1/0, o serviço respondeu HTTP/1.1 202 Accepted. Sendo assim o Framework de tratamento de erro que estamos construindo e o seu correto uso tornam-se fundamentais.

Serviços Request-Response

  • O GlassFish ESB… 
    • Retorna o status HTTP/1.1 200 OK quando…
      • A requisição foi processada sem problemas. Esse código indica que bem, esse tudo mundo sabe, né?!? A diferença para o código 202 Accepted é que nesse caso o serviço enviou um conteúdo no corpo da mensagem. O consumidor do serviço poderá decidir, por exemplo, se precisa realizar alguma outra ação.
    • Retorna o status HTTP/1.1 500 Internal Server Error quando…
      • Dentro do BPEL capturarmos alguma exception, fizermos o devido tratamento e respondermos para o cliente uma mensagem do tipo Fault no corpo da mensagem. Sendo assim, o provedor do serviço também envia algum conteúdo no corpo da mensagem.

O interessante disso tudo foi constatar a fidelidade do GlassFish ESB em relação aos cabeçalhos HTTP de resposta.

Acredito que essas informações possam nos ajudar a desenvolver serviços no GlassFish ESB de forma mais segura (no sentido de saber mais sobre o comportamento da ferramenta) e também implementar consumidores de serviços ainda mais refinados.

Abraços a todos e até o próximo post!

Correlação de Mensagens utilizando BPEL


Na especificação BPEL correlação é uma funcionalidade importante que precisa ser entendida por aqueles que ou irão projetar processos complexos ou irão desenvolver aplicações que utilizarão tais processos. Isso porque a correlação de mensagens em BPEL (Business Processo Execution Language) é uma das funcionalidades que permitem a elaboração de cenários complexos onde diferentes “parceiros” (partners – consumidores ou provedores de serviços) estão envolvidos na execução de uma instância de processo.

O que é uma instância de processo?

Apenas para que fique claro o que é uma instância de um processo, vamos fazer uma breve analogia à linguagem Java. Quando escrevemos uma classe em um arquivo “.java” estamos codificando a sua definição ou declaração. Ao compilar e executar essa classe em uma máquina virtual Java teremos um objeto dessa classe, ou seja, uma instância da classe. (Logicamente que, dependendo da situação, podemos ter em execução mais de uma instância dessa classe). Sendo assim, podemos fazer a seguinte analogia:

  • Em tempo de projeto ou codificação:
    • Uma classe Java equivale à definição de um processo;
  • Em tempo de execução:
    •  A Java Virtual Machine (JVM) equivale a um motor (engine) BPEL;
    • Um objeto Java em uma JVM equivale a uma instância do processo em um engine BPEL.

Entendendo o problema de correlação.

Antes de começar a falar de BPEL (Business Processo Execution Language) e sobre correlação vamos começar entendendo o contexto em que utilizamos a palavra correlação. Segundo o dicionário Michaelis:

correlatar
cor.re.la.tar
(co+relatar) vtd 1 Estabelecer relação mútua. vpr 2 Entrar ou estar em correlação com.


Quando falamos em correlação no contexto de processos e de BPEL, estamos nos referindo a como relacionar diferentes instâncias de um processo aos seus devidos usuários, ou ainda, como correlacionar diferentes mensagens que são recebidas em momentos distintos e eventualmente por fontes distintas.

Vamos a um exemplo prático utilizando o seguinte processo fictício:

Esse processo possui 2 tarefas (ou atividades) que no caso foram chamadas de “1o processamento” e “2o processamento“. A dinâmica do processo ocorre da seguinte forma:

  1. Toda vez que uma “Mensagem tipo X” chega ao engine BPEL uma nova instância do processo é criada;
  2. A tarefa “1o processamento” é acionada de forma a consumir a mensagem;
  3. Como a tarefa “2o processamento” depende da chegada da “Mensagem tipo Y“, o engine BPEL coloca instância do processo em pausa para aguardá-la
  4. Quando a “Mensagem tipo Y” chega, a instância do processo sai do estado de pausa e a tarefa “2o processamento” é executada;
  5. O processo termina e a instância é finalizada pelo engine BPEL.

Agora observe a figura abaixo onde há mais de uma instância do processo em pausa, cada uma aguardando a chegada da sua  segunda mensagem. A qual instância de processo o engine BPEL deverá enviar a próxima “Mensagem tipo Y” que chegar?

O que o engine BPEL precisa descobrir é qual instância de processo foi criada pela “Mensagem tipo X” que possui correlação com a “Mensagem tipo Y” que está chegando. Vamos ver como a especificação BPEL trata esse problema?

Como a correlação pode ser implementada?

Quem está acostumado a trabalhar com linguagens de programação web deve estar pensando que isso pode ser facilmente implementado usando sessões (sessions). Mas e se eu dissesse que a especificação BPEL não resolve essa questão utilizando sessões?

O que acontece é que um das principais observações feitas pelo grupo especificou o BPEL é que a maioria das mensagens trocadas entre partners e processos já carregam os dados requeridos para identificar unicamente a instância de um processo, ou seja, dados que tornam possível a correlação de mensagens enviadas em momentos diferente. Por esse motivo a especificação BPEL recomenda que a correlação seja implementada usando dados funcionais da mensagem, ou seja, dados existentes no conteúdo da mensagem. Voltando ao nosso exemplo, poderíamos considerar que a “Mensagem tipo X” seria um pedido de reserva de espaço para um anúncio em um jornal, enquanto que a “Mensagem tipo Y” equivaleria à confirmação da reserva. Nesse caso, as duas mensagens poderiam ser correlacionadas simplesmente por uma ID do anunciante ou por algum outra chave, seja ela simples ou composta, que permitisse identificar unicamente cada pedido.

O grande benefício que a maiorida dos engines BPEL proporcionam é o suporte oferecido por eles para a recuperação da correta instância de processo a partir da correlação de mensagens.

Quer mais detalhes sobre correlação? Sugiro como leitura a parte da especificação BPEL que trata a questão de correlação de mensagens. Em seguida vale conhecer melhor como as ferramentas que você tem disponível implementam essa parte da especificação.

Em um próximo post mostrarei como implementar a correlação de mensagens em um processo BPEL na ferramenta GlassFish ESB.

Até lá !

JBI – “O barramento dentro do barramento”


Java Business Integration, ou simplesmente JBI, é um framework que define uma arquitetura de integração de componentes plugáveis e um modelo de troca de mensagens entre esses componentes. Nessa arquitetura, diferentes componentes podem ser conectados a um mediador de mensagens, e interoperar ou colaborar com os demais componentes do ambiente. O JBI é especificado pela JSR-208.

Existe uma maneira bem fácil de entender a arquitetura do JBI. Imagine um barramento de serviços (ESB) de  uma Arquitetura Orientada a Serviços (SOA). Provavelmente você deve ter imaginado uma imagem parecida como a abaixo.

Figura 1 – Visão de uma arquitetura SOA com ESB

Se esse não foi o caso, não tem problema. O que acontece é que a maioria dos desenhos que explicam um barramento de serviços possui um formato como esse, onde:

  • Camada 1: Trata-se dos serviços, ou seja, da exposição de funcionalidades e/ou regras de negócio de sistemas existentes;
  • Camada 2: Representa a interação dos serviços com o barramento para colaboração com os demais serviços ligados ao barramento. Quando falamos de web services, essa camada poderia ser, por exemplo, SOAP ou REST;
  • Camada 3: É o barramento de serviços ou ESB, que faz a mediação da comunicação entre os serviços.

Antes de fazer a analogia de SOA com a arquitetura JBI precisamos conhecer alguns integrantes de um ambiente JBI. São eles:

  • Binding Components (BC): São componentes que fazem a ligação do ambiente JBI com o mundo externo. Eles são as portas de entrada e saída para o ambiente JBI;
  • Service Engines (SE): São componentes do ambiente JBI que processam dados que chegam através dos Binding Components e, quase sempre, enviam uma resposta através do mesm ou ou de outro Binding Component;
  • Normalized Message Router (NMR): BCs e SEs se comunicam trocando mensagens padronizadas. Essa comunicação é mediada pelo NMR.

Provavelmente você já deve ter começado a encaixar os BCs, SEs e o NMR na figura que apresentamos acima. Vamos ver como ficaria isso?

Figura 2 – Visão de uma arquitetura JBI

 

Por questões didáticas mostramos os SEs na parte de cima da Camada 1 e os BCs na parte de baixo. A Camada 2 representa a forma de comunicação entre BCs e SEs através do NMR, que por sua vez está na Camada 3. Em linhas gerais, a dinâmica de funcionamento típico de um ambiente JBI segue o seguinte processo:

  1. Uma mensagem chega em um BC através de algum protocolo de comunicação (Ex: SOAP, REST, JMS, FTP, CIFS, SMTP etc);
  2. O próprio BC normaliza a mensagem, ou seja, padroniza a menssagem para que ela possa trafegar dentro do ambiente JBI e chegar até um SE ou outro BC;
  3. O BC envia a menssagem normalizada para o NMR;
  4. O NMR entrega a mensagem para um SE;
  5. O SE processa a mensagem e devolve a resposta para o NMR;
  6. O NMR envia a mensagem de volta ao BC original ou a outro BC.
  7. O BC que receber a mensagem desnormaliza e transforma a mensagem para o padrão de comeunicação implementado por el (Ex: SOAP, REST, JMS, FTP, CIFS, SMTP etc).

Essa é a visão estrutural de como um ambiente JBI funciona. Quando digo “ambiente JBI” refiro-me a qualquer servidor que implemente a especificação JBI. Alguns servidores que implementam são: Oracle Glassfish ESB (Open ESB), Apache Service MixPetals ESB etc.

Cada um desses produtos possui um conjunto de implementações de Binding Componentes e Service Engines. As figuras abaixo representam um resumo dos BCs e SEs implementados pelo Apache Service Mix e pelo Oracle GlassFish ESB. Inclusive percebe-se que foi a imagem do Service Mix que eu utilizei como exemplo para fazer a analogia com SOA 🙂

Figura 3 – Alguns componentes do Apache Service Mix

A listagem completa dos componentes implementados pelo Service Mix está |aqui|.

Figura 4 – Alguns componentes do Oracle GlassFish ESB

 

A listagem completa dos componentes implementados pelo GlassFish ESB está |aqui|.

Na prática o que podemos fazer em um ambiente JBI?

Como o JBI é baseado em troca de mensagens através do NMR, existem alguns padrões de trocas de mensagens (Message Exchange Patterns) definidos na especificação, tais como In-OnlyIn-OutRobust In-OnlyIn Optional Out etc [1][2]. Não entrarei nesse nível de detalhe aqui nesse post. Por outro lado, vamos a alguns casos de uso práticos desses padrões:

  • Configurar um JMS BC para escutar uma fila JMS e, ao chegar uma mensagem, redirecionar o seu conteúdo para um web service implementado usando SOAP através do SOAP BC ou HTTP BC;
  • Orquestrar diferentes serviços disponibilizados como SOAP (SOAP BC ou HTTP BC) ou EJB (EJB SE);
  • Expor como um web service a view de um banco de dados, ou seja, implementar um Data Services;
  • Monitorar uma pasta de rede através de CIFS (File BC) ou FTP BC e, ao chegar um arquivo, processar seu conteúdo de forma a inserí-lo em um banco de dados através de JDBC;

Certamente você seria capaz de fazer tudo isso usando sua linguagem de programação predileta e com a ajuda de algumas bibliotecas e frameworks. O grande benefício do uso de um JBI é que você consegue fazer isso tudo de maneira muito fácil, rápida e sem escrever praticamente nenhuma linha de código. Isso porque ao invés de programar você apenas configura os componentes para funcionarem da forma desejada e colaborarem para, em conjunto, atinginrem os requisitos e objetivos desejados.

Enfim, são várias as possibilidades de integrações que  podem ser implementadas. Tudo depende da necessidade, das implementações de BCs e SEs disponíveis no ambiente que você escolher e também, por que não dizer, da sua criatividade.

Finalmente, qual o motivo desse post ter o título “O barramento dentro do barramento”?

Isso deve-se ao fato da possibilidade de uso do JBI como um ESB. Como o JBI possui um “barramento” interno, que é o NMR, ao usar o JBI como um ESB teremos “um barramento (NMR) dentro do barramento  (ESB)”. Na prática, o que faríamos seria:

  1. Conectar serviços ao barramento (ESB) através do BC apropriado, ou seja, de acordo com o protocolo falado pelo serviço;
  2. Escolher o SE apropriado para processar a requisição de um serviço (Ex: rotear, log, transformar mensagem etc); e
  3. Devolver uma resposta, se necessário, através do BC original ou de um outro BC, caso o protocolo de resposta seja diferente do protocolo da requisição original.

Open source ESB


Ao acender das luzes de 2010 foi lançada a nova versão do GlassFish Open ESB, um barramento corporativo de serviços que é a ferramenta principal de uma SOA, que implementa o JBI (JSR-208) e é suportado pela Sun.

Nessa nova versão, além de algumas correções de bugs, o GlassFish ESB v.2.2 teve mais 3 componentes JBI promovidos para o status Released, o que significa que eles passam a ter suporte comercial da Sun uma vez que passaram pelo processo de teste e QA (Quality Assurance). São eles:

  • Email Binding Component: Um Binding Component que suporta a configuração e conexão a servidores de email permitindo o envio e o recebimento de mensagens;
  • REST Binding ComponentUm Binding Component que fornece conectividade de e para o barramento através de RESTful webservices, ou seja, agora sistemas externos poderão invocar usando REST as aplicações compostas hospedadas no GlassFish ESB assim como tais aplicações poderão acessar web services REST;
  • POJO Service Engine: Um Service Engine que permite a definição da lógica de negócio usando Java no estilo Plain Old Java Objects de forma simples e flexível.
Além disso, enquanto a versão 2.1 do GlassFish ESB vinha com o NetBeans 6.5, a nova versão é disponibilizada com o NetBeans 6.7.1.

Outra novidade é que a Sun criou 2 pacotes adicionais: Sun GlassFish ESB Health Care Pack e o Sun GlassFish ESB Platinum Pack. O que são eles?

Sun GlassFish ESB Health Care Pack: Um pacote que implementa facilidades para o uso de certos padrões de sistemas da área médica, como por exemplo o HL7 e o PIX/PDQ.

Sun GlassFish ESB Platinum Pack: Trata-se de um pacote que extende as funcionalidades do pacote padrão possuindo componentes adicionais tais como:

  • Worklist Manager Service Engine: Um Service Engine que permite a definição de processos human-centric que objetivam a automação de tarefas manuais e a implementação de workflows;
  • IEP Service Engine: Um Service Engine que implementa funcionaliade de Complex Event Processing (CEP) e Event Stream Processing (ESP).
  • COBOL Copybook Encoder: Um codificador baseado em campos de tamanho fixo que possibilita a definição e teste de COBOL Copybook encoders com suporte para runtime;
  • BPEL Monitor: Tratase de uma ferramenta de monitoração em tempo real dos processos implementados usando o BPEL Service Engine
  • Event Management Console: Trata-se de uma ferramenta de monitoramento e emissão de alertas sobre eventos ocorridos em aplicações hospedadas no GlassFish ESB.

Mas nem tudo são flores nesse lançamento. Tão logo a novidade foi anunciada, a comunidade do Open ESB começou a questionar o fato do código-fonte das novas versões do Worklist Manager e do IEP não terem sido disponibilizados. Especulações a parte, o fato é que isso pegou de surpresa alguns membros da comunidade que estavam participando do desenvolvimento uma vez que o repositório de fontes não teria sido devidamente atualizado com a nova versão e eles ficam sem saber o que fazer com o que estava no seu Sandbox. A discussão segue no Forum dos usários do Open ESB.