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!

RESTful Web Services: When to use POST or PUT?


From time to time I have a discussion with my workmate Carlos Filho and our Architecture team at Infoglobo about the use of POST and PUT when developing RESTful webservices. Such discussion happens because we always get confused on when to use POST and when to use PUT.

The convention I’m going to explain here was not stated by us. It’s a definition made by Leonard Richardson and Sam Ruby in RESTful Web Services (Web services for the real world) published in 2007.

When to use POST

Scenario 1) If the client wants the service to create a resource but the client is not sure how (or don’t know) the resource’s URI is going to look like in advance
For example, let’s say you are designing a Restful web service to deal with Products. A possible solution for a product creation would be…
POST /product
…where you would, let’s say, send a XML representation with all product’s specific attributes.
This way the service would could take either a product ID or a auto-generated code to compose this product’s URI and return this URI in the Location HTTP header response. Therefore, the response header to the POST /product request would have something like…
...
Location: /product/1234
...
…where 1234 is the product’s identifier whe talked about.
Scenario 2) If the client wants the service to append a resource to a collection but the client is not sure (or don’t know) how the resource’s URI is going to look like in advance
This is scenario is very similay to the previous one. Considering you have a product catalog you would issue a…
POST /surf-boards-catalog
…and the service would return a Location header such as…
...
Location: /surf-boards-catalog/product/1234
...

Tha’s pretty the same as the first scenario.

When to use PUT

Scenario 1) If the client wants the service to update a resource identified by an URI that the  client knows in advance

This is the case where the client is going to use the URI provided by the service. This URI in the one in Location header provided by the service in the response to the POST request that created the resource.

Scenario 2) If the client wants the service to create a resource identified by an URI that the  client knows in advance

When it’s the client who will decide how will be the resource’s URI, and not the service, the client should use PUT. In this scenario, of course the service knows the URI’s pattern but it’s the client who will tell the service what will be each one of the variable URI parts.

We had an example at Infoglobo of such scenario. We created a RESTful web service that will be consumed by iPhone,  iPad and Android applications developed by Infoglobo. The first time the application is opened it will issue a request to this RESTful service to tell it there is a new device where the application was installed.

Each device is identified by an token and each application has a specific identification depending on the device’s operational system. This way we defined that each applilcation would issue a PUT request such as…

POST /application/[app-id]/platform/[platform-id]/device/[device-token]

In this scenario the service doesn’t know in advance all device tokens and we decided not to register or create all applications and platforms in advance. All of it is done in this single request. Although the service knows the URL pattern  it’s up to the client to define how the final URI looks like.

Hope that helps you when designing your next RESTful web service.

Contrato de Serviços REST


Ao longo das últimas semanas venho pesquisado e análisado várias abordagens diferentes sobre como implementar serviços seguindo o estilo REST, e fiquei muito intrigado em como descrever ou não a sua interface e os dados associados a eles.

Pois então, logo que me deparei com REST, tive a impressão de que as pessoas preferiam implementar serviços onde suas mensagens eram Json, pura e simplesmente por não entenderem de fato XML e quererem fugir de qualquer coisa que remeta ao wsdl e XML Schema dos Webservices. Infelizmente para muitos o wsdl é apenas um arquivo que você utiliza passar ao framework de webservices  para poder se comunicar com o serviço, mas de fato não sabem o que ele contém e que de fato ele é um contrato, ou seja, que funcionalidades este serviço te oferece, como interagir com elas, quais as restrições e onde está este serviço.

Mas depois lendo mais relatos e conversando com outros profissionais da área, pude perceber que minha primeira percepção não estava errada mas também que estas pessoas citadas acima são apenas parte das pessoas que apoiam REST e Json.  De fato a combinação dos 2 pode trazer muitos benefícios, como por exemplo simplicidade e performance. O que de fato ainda não me deixa ficar tranquilo são as implementações de serviços que recebem e respondem mensagens em Json mas não tem um contrato de dados. Por exemplo, uma solução para isso seria o uso de JSON Schema, que pode ser usado para garantir que as mensagens estejam formatadas de acordo com o que o serviço se propoe a fazer e ainda pode e deve ajudar o cliente na hora de consumi-lo.  Acredito que quando os validadores de Json ficarem mais maduros esta será uma boa prática. Por em quanto o XML Schema ainda ganha quando nos preocupamos com contrato de dados.

Outra questão que vale a pena comentar é a do uso de WSDL para descrever serviços REST. Então.. depois ler uma parte específica sobre WSDL 2.0 Bindings do livro “Web Service Contract Design & Versioning – Thomas Erl”l, fiquei cada vez mais interessado nesta abordagem e pouco tempo depois um caso específico me chamou muita atenção (Ebay). Eles resolveram que para cada serviço que estava no repositório corporativo, deveria ter um WSDL com a usual definição de dados em XML Schema, mas sempre ter 2 bidings definidos, um para SOAP e outro para HTTP. Ou seja, aquela mesma funcionalidade poderia ser consumida usando mensagens SOAP quanto requests HTTP “puros”, utilizando os métodos/verbos HTTP.

De positivo que me salta aos olhos são a flexibilidade na forma de consumir o serviço, e a oportunidade desta decisão ser tomada caso a caso e não em tempo de definição do serviço. Agora se você ler um pouco sobre o que é REST e refletir sobre este assunto, você se depara com uma questão que incomoda a quem defende REST que inclusive eu mencionei no post anterior. Já que o serviços REST tem uma interface padrão, URI + HTTP Verbs, faz apenas sentido definir os dados que serão recebidos e enviados do serviço.

Bom estes foram alguns pensamentos sobre REST, Json, e Contrato de dados.
Opine! Comente! Compartilhe!

Qual a diferença entre REST e SOAP?


Bom, vamos lá.. Quem é que nunca leu algum artigo, presenciou ou de fato iniciou uma discussão sobre REST e SOAP? Acho que muitos.. certo?!

Então… Logo após de ler o título deste post você deve estar se perguntando “Esse cara vai ser mais um desses que fica defendendo um lado e detonando o outro com argumentos esquerdistas e radicais?” De ante mão te respondo: “Não!”. Minha intenção com este post é apenas explicar um pouco sobre o assunto e tentar desfazer algumas confusões que as pessoas fazem com REST, SOAP e outros assuntos adjacentes.

Antes de mais nada, vamos a definição básica destes dois:

REST – Representational State Transfer é um estilo arquitetural usado no projeto de aplicações da Web que contam com recursos nomeados (URL,URI,URN) e engenhosamente utiliza mais profundamente o protocolo HTTP, seu cabeçalho , seus métodos (GET, POST, PUT, DELETE, HEAD) e toda a infraestrutura web já bem estabelecida, reconhecida e utilizada por todos.

SOAP – Simple Object Access Protocol é um protocolo para troca de informações estruturadas geralmente em uma plataforma descentralizada e distribuída. Ele se baseia em XML para seu formato de mensagem, ou seja, uma mensagem SOAP encapsula o conteúdo e pode ser trafegada via HTTP, JMS ou outro protocolo.

Se você, por um acaso, antes de ler este post achou que SOAP tinha alguma coisa a ver com sabão e REST com descanso.. você precisa ler mais. 😛

Brincadeiras à parte…, vamos a algumas questões que são importantes nesta discussão.

1 – Definição de interfaces

Primeiramente, pensando em serviços que utilizam mensagems no protocolo SOAP, o mais comum é descrevermos a interface do mesmo com WSDL (Web Services Description Language). Basicamente, cada serviço terá um arquivo .wsdl que terá a definição de suas operações, estrutura de dados que são usadas nas requisições e respostas, Endpoints (endereços de rede do serviço). Uma associação que ajuda o entendimento deste ponto é pensarmos nas operações como métodos de uma classe, a assinatura do método como as mensagens definidas, e o tipo de cada campo da assinatura a definição da estrutura de dados que será usadas nas mensagens.

Agora, nos serviços RESTful, se seguirmos de fato o estilo, parte da descrição da interface é desnecessária já que a forma de interagir com os serviços é sempre a mesma , por meio dos métodos http. E ainda mais com o uso do Método Option podemos saber quais outros métodos são permitidos naquele serviço. Agora com relação aos dados continua a ser interessante a definição de que dados vão trafegar e suas restrições.

Agora, tem pessoas que mesmo assim preferem de uma definição tanto dados quanto de operações, e estas podem fazer o seguinte:

a) Criar um documento para ser lido por humanos que pode conter, por exemplo, a estrutura de dados que seu serviço recebe e responde, lista de quais operações HTTP estão sendo suportadas naquele serviço, qual formato de mensagem é suportado, etc.. Na minha opinião, esta abordagem faz mais sentido quando a estrutura de dados da mensagem é simples e/ou utiliza notações simples como JSON por exemplo, devido a facilidade da implementação do código que irá acessar ao serviço.

b) A segunda forma, é utilizar o WADL(Web Application Description Language), ele é similar ao WSDL só que mais simples, com artibutos de configuração que facilitam a compreensão, por exemplo, de qual notação/formato é utilizada nas mensagens de request e response, e o mais importante, é todo orientado aos recursos e ao protocolo HTTP.

Obs:
WSDL e WADL serve para que aplicações clientes/consumidoras possam gerar o código automaticamente a partir destas definições. No entanto, nada impede que trasnformações .XSL sejam aplicadas a estes arquivos e eles fiquem mais “legíveis” para leigos, afinal os dois são XML com schema e com vocabulário bem definido.

2 – SOAP e SOA

Preciso começar este tópico com uma frase clássica, “uma coisa é uma coisa outra coisa é outra coisa”. Nem adianta falar que a diferença entre SOAP e SOA é a letra “P” essa já está velha.

Primeiro, SOAP é um protocolo para troca de informações estruturada, como vimos no início deste post. SOA, por sua vez, é uma arquitetura que se baseia no paradigma de orientação a serviço que molda o desenvolvimento de funcionalidades de negócio, buscando desacoplamento, reutilização, produtividade e alinhamento entre objetivos de negócio e as estratégias de TI. (SOA Manifesto)

Além do nome ser parecido, o que faz com que as pessoas troquem um pelo outro em conversas, e leigos que estão escutando multiplicarem esta confusão por aí…, existe também uma questão relacionada tanto aos big vendors de ferramentas, quanto aos consultores tradicionais atrelados à SOA, que focam muito em Web services, WSDL, WS-* Extensions e SOAP. Ainda tem o fato adicional de que a maioria deles estão engatinhando em REST. Ou seja…, tem muitos profissionais de TI, inclusive que se dizem entendidos de SOA, que acham que para se ter uma Arquitetura Orientada a serviço precisamos de Webservices, WSDLs e SOAP, o que está 100% errado.

3 – Algumas questões que podem desfazer algumas amarras entre estes conceitos

a) Podemos ter uma empresa com uma maturidade elevada em SOA, apenas com serviços RESTful? SIM!

b) Podemos ter serviços RESTful com a interface descrita com WSDL.? SIM! É! com WSDL.. WSDL foi criado para descrever interfaces e tem uma boa flexibilidade, podemos usar SOAP sobre HTTP, ou simplesmente HTTP com mensagens em formato JSON, ou XML. (obs: Apartir do WSDL 2.0 isto ficou mais fácil.)

c) Podemos ter serviços disponíveis em HTTP e não serem serviços REstful? SIM! Formas de utilizar o cabeçalho HTTP, como modelar as URLS, e usar operações GET, POST, PUT, DELETE entre outras coisas vão determinar se o serviço é RESTful ou não.

4 – SOAP ou REST ?

Podemos elencar alguns pontos interessantes:

Rest
– É mais elegante, pois utiliza ao máximo o protocolo HTTP, evitando a construção de protocolos adicionais
– Tem o potencial de ser bem mais simples que uma implementação com WSDL/SOAP
– Tende a ser mais performático
– ~ 80% das integrações utilizam o protocolo HTTP.
– A possibilidade de ter difersças representações de um mesmo recurso, por exemplo, uma dada entidade pode ser representada em diferentes formatos como Json, xml, html e text/plain, dependendo da requisição feita pelo cliente(Content-Negotiation)
– Possibilidade de navegar entre relacionamentos (Links web) de vários recursos de forma dinamica. seguindo a usabilidade de qualquer sistema web. HATEOAS (Hypermedia as the Engine of Application State).

SOAP
– É um padrão que combinado a as especificações WS-* podem garantir questões de QoS(Quality of Service), Segurança, transação e outras questões presentes em integrações mais complexas.
– Uma mensagem SOAP pode ser propagada por diferentes protocolos, o que flexibiliza bastante várias integrações.
– É um padrão que está muito maduro no mercado, qualquer ferramenta de integração e Framework tem várias funcionalidades para manipular as mensagens que seguem este padrão.

Com certeza existem muitos outros pontos a serem levantados, mas de qualquer forma.. Minha resposta para a pergunta tão popular “Qual o melhor?” seria “Depende”.. depende de qual problema você quer resolver.

Particularmente, acredito que cada demanda tem que ser analisada, com calma, por pessoas que conheçam as 2 abordagens e possam chegar a uma solução adequada ao problema em questão. Isto me faz lembrar de um artigo que o Marcelo Fernandes(companheiro de equipe), me encaminhou há algum tempo que falava sobre uma metodolia ágil muito extremista mas que tinha uma frase interessante.. algo como “Tudo aquilo que você considera verdade, está errado em algum contexto” ou seja, achar uma solução antes de entender o problema é algo que pode funcionar algumas vezes, mas tem um risco, e com certeza em algum, ou vários contextos aquilo não irá se aplicar.. então.. analise cada caso e tire proveito de cada um dos dois.

Abraços,

Carlos Alberto Filho

Pode existir SOA com REST?


Essa semana assisti a gravação de uma apresentação de um arquiteto da plataforma de comércio eletrônico da EBay (Sastry Malladi). A apresentação, realizada na QCon de 2010 (San Francisco, USA), fala sobre algumas formas de implementar serviços REST (RESTful services) numa arquitetura orientada a serviços (SOA) que normalmente contem serviços SOAP e os padrões WS-*.

A apresentação é mais uma demonstração prática de que serviços REST podem ser parte integrante de SOA. Na minha opinião poderíamos ir até mais longe. Isso porque eu arriscaria dizer que serviços REST devem ser sempre considerados pois nem sempre é necessário implementar os padrões WS-*.

Um ponto interessante na apresentação foi a utilização de JAXB para gerar representações em formatos JSON, coisa que por coincidência eu venho implementando juntamente com o Jersey. A flexibilidade oferecida pela dobradinha Jersey e JAXB é muito boa e me lembrou um pouco o Ruby on Rails. Pretendo em breve falar mais sobre o assunto aqui no blog.

Um ponto que a demonstração prática deixou a desejar foi mostrar com mais detalhes o uso dos XMLs de mapeamento. Fiquei com a impressão de que muito código deve ser construído e mantido para suportar as integrações, coisa que uma ferramenta de ESB ou EAI tiraria de letra.

A apresentação, sugerida pelo meu amigo e arquiteto de integração Carlos Alberto Filho, está no site da InfoQ em http://www.infoq.com/presentations/RESTful-SOA-in-the-Real-World

Conhecendo o Ruby On Rails


Há mais ou menos uns 10 anos atrás, comecei a perceber o grande e repetitivo trabalho que tinha que fazer toda vez que eu tinha que iniciar o desenvolvimento de um sistema usando as linguagens PHP (Na época chamado de PHP FI) ou ASP.

Ter que criar scripts e tabelas no banco de dados sempre partindo do zero era uma coisa que tornava o trabalho demorado e sem graça, quase que puramente operacional. Foi quando recorri ao “The most powerful and useful guide to the Net” (aka: Altavista), procurando por algo que pudesse agilizar meu trabalho tornando-o mais produtivo e divertido. A busca foi frustrada pois o melhor que eu encontrei naquela época foi o Dreamweaver UltraDev, que simplesmente criava um código impossível de dar manutenção.

Passado todo esse tempo, eis que em 2010 posso dizer encontrei o que procurava naquela época. Depois de escutar vários amigos falando muito bem e usando, resolvi conhecer e praticar o Ruby on Rails.

O primeiro passo foi dado com a leitura do (excelente!) livro “Ruby on Rails – Desenvolvimento rápido e fácil de aplicações web” do Robrigo Urubatan (Editora Novatec).

Já nos primeiros capítulos não resisti e comecei a colocar a mão na massa, ou seja, instalei o Ruby on Rails e comecei a criar algumas aplicações a partir dos exemplos contidos no livro. A experiência não poderia ser melhor!!

Ruby on Rails, também chamado de RoR, é um framework de desenvolvimento de aplicações web baseado na linguagem Ruby e que utiliza o padrão arquitetural Model-View-Controller (MVC).

Uma característica muito interessante desse framework é a utilização nativa de web services REST como forma de comunicação entre o View e o Controller. Sendo assim, ao criar uma aplicação web com o Ruby On Rails você não só está criando a interface humana (HTML) do seu sistema mas também está disponibilizando toda a lógica da sua aplicação para acesso através de uma API REST, o que me interessou muito já que estou atuando como Arquiteto de Integração e participando da implantação de uma Arquitetura Orientada a Serviços (SOA).

Quer ver como é fácil desenvolver aplicações web com o Ruby on Rails?

Desde quando pensei em escrever esse post fiquei pensando o que faria para mostrar brevemente como o Rails funciona. Que exemplo utilizar? Devo, antes de tudo, mostrar como se instala o Ruby e o Rails? Será que o post não vai ficar chato e grande? Nada disso! Foi então que lembrei de um vídeo que me serviu como grande motivador para aprender o framework.

Trata-se de dois vídeos que explicam como trabalhar com formulários html aninhados. No vídeo, a aplicação que é construída permite a criação de Pesquisas (surveys), onde cada pesquisa pode conter várias perguntas, que por sua vez pode conter várias opções de resposta.

Mesmo se você não sabe nada de Ruby ou de Rails vale a pena assistir. Mas assista observando a (pouquíssima) quantidade de código que é escrita para criar a aplicação. Observe também o tempo que leva para fazer. E, principalmente, pense na quantidade de código que você teria que escrever e quanto tempo demoraria para você fazer o mesmo na linguagem de programação que você utiliza atualmente.

Aí vai o link desses dois vídeos que estou me referindo:

A propósito, o http://railscasts.com é uma ótima referência para aprender a como resolver uma série de problemas recorrentes que nos deparamos no dia a dia do desenvolvimento de aplicações web.

O que torna no Ruby on Rails tão simples?

Você já ouviu falar em “Convenção sobre Configuração”? Talvez tenha ouvido falar com o nome de “Codificação por convenção”? Não???????

Bem, o Rails é um framework que segue esse conceito. Na prática, o que tal conceito prega é que o desenvolvedor não precisa dizer, ou melhor, configurar, como o framework irá se comportar toda vez que for construir uma aplicação. Isso quer dizer que o framework assume determinadas premissas de funcionamento e que o desenvolvedor só terá algum trabalho se precisar alterar tais premissas (o que só acontece em casos muito específicos).

Alguns exemplos de tais premissas, ou melhor, convenções, são:

  • A comunicação entre a View e o Controller é feita por REST com os verbos HTTP: GET, POST, PUT e DELETE;
  • Alguns métodos de um Controller são mapeados automaticamente aos verbos HTTP: GET é mapeado ao método show, PUT ao método create, POST ao método edit e DELETE ao método destroy.
  • Toda View já possui uma saída HTML, para consumo humano, e uma XML para consumo por um programa (cliente do web service);
  • Não é necessário criar arquivos de Mapeamento Objeto-Relacional. Isso já está embutido em todo modelo;

Essa lista poderia ir longe. A importante mensagem que espero ter passdo com esse pequeno exemplo é: Poupa-se muito trabalho ao utilizar essa abordagem!

Saiba mais sobre Convenção sobre Configuração.

Quer aprender Ruby on Rails e não sabe por onde começar?

Começar aprendendo a linguagem Ruby é sempre uma boa, a final de contas não dá para aprender direito um framework de desenvolvimento sem saber a linguagem que ele utiliza.

Para aqueles que não dispõem se muito tempo e querem aprender Ruby e Rails colocando a mão na massa desde o início, adquira o livro que eu comentei no começo desse post. Mas atenção!!! Esse livro trata da versão 2 do Rails, que já está na versão 3.

Se o Inglês não for um problema e você quiser iniciar o aprendizado na recente versão mais recente, leia o livro “Agile Development with Ruby on Rails (3rd Edition)“. Nele você construirá uma aplicação completa de e-commerce onde são abordadas situações reais que enfrentamos no dia a dia do desenvolvimento de aplicações web. Eu lí ambos e recomendo.

Outra boa sugestão é seguir as dicas do Akita sobre como aprender Ruby on Rails. A propósito, o blog dele (http://akitaonrails.com/) é uma ótima maneira de manter-se antenado sobre o que rola na comunidade Rails aqui no Brasil.

Abraços e até a próxima!