Precisamos de um descritor de serviços REST?

Me perguntaram sobre isso na minha apresentação de REST na Globo.com e isso foi assunto de uma discussão interessante hoje no CEJUG. Como é um assunto que pode interessar a bastante gente e eu me interesso muito por web services, resolvi falar mais sobre isso aqui no blog.

Os web services WS-* possuem o WSDL (Web Services Description Language), um artefato amplamente aceito que descreve de forma padrão os serviços da aplicação. Ao especificar no WSDL quais são os schemas XML dos documentos que serão trocados e a cardinalidade precisa de cada elemento, conseguimos garantir que qualquer cliente que entenda o padrão estabelecido será capaz de interpretar os documentos e comunicar-se corretamente com os serviços. Além disto, a maturidade deste padrão traz a vantagem de que já existem geradores de clientes em várias linguagens a partir de um documento WSDL.

Entretanto, WSDL (bem como muita coisa em WS-*) é complexo. Um ser humano que tenha que analisar um WSDL grande perderá um bom tempo para entender o que está descrito no documento. Já REST não tem uma forma padrão de especificar os contratos dos serviços.

Embora a versão 2.0 da especificação WSDL permita descrever web services REST, os principais projetos open source da área como o Apache Abdera, Google Data API, Jersey e o Mule não utilizam esta forma de publicação. Não tenho conhecimento de nenhum projeto publicamente divulgado que faça uso do WSDL 2.0 para descrever serviços REST, e a adoção desta capacidade é baixíssima (se é que existe).

O projeto Jersey oferece opcionalmente o WADL, que é uma forma de descrever serviços REST. Confesso que ainda não olhei o WADL para ver se seria interessante usá-lo. Pelo que sei, entretanto, a adoção dele também é muito baixa.

Existe também o documento de serviços do AtomPub, que é bem interessante. Ele é um documento simples que lista quais são as coleções disponíveis e a localização das mesmas. O documento informa também quais são os MIME types aceitos em cada coleção.

Eu considero interessante que a aplicação ofereça uma interface simples de consulta dos serviços disponíveis. Não é obrigatório, mas quando a aplicação tem uma certa quantidade de clientes é bem legal ter isso para facilitar.

Em dois projetos que eu trabalhei, eu implementei um Servlet simples que listava todas as URIs disponíveis na aplicação, quais métodos HTTP são aceitos em cada uma das URIs e além disso um exemplo de XML manipulado em cada uma das URIs. Isso foi algo que eu achei bom o suficiente, e não tão custoso. Normalmente a documentação de verdade dos serviços fica em algum lugar como uma Wiki, ou uma página qualquer com a descrição detalhada de como interagir com os serviços.

A questão principal é que quando você segue as boas práticas de desenvolvimento REST, os seus serviços ficam muito mais claros para quem precisa se integrar. Por exemplo, eu trabalhei em um projeto crítico de integração com o Google esse ano. Tive que usar várias funcionalidades da Google Data API. A API deles é REST, e encapsula os dados com o formato Atom. Eles não oferecem nenhuma interface semelhante ao WSDL, eles simplesmente têm uma página com a documentação dos serviços.

Como eles seguiram as boas práticas de implementação REST, eu rapidamente aprendi a utilizar a API deles. Os protocolos de comunicação REST são bem semelhantes, e mais simples de entender do que qualquer coisa com WS-*. Pouco mais de 1 hora depois de olhar a documentação deles, eu já estava conseguindo me integrar com eles, com os primeiros exemplos.

O Guilherme fez uma observação interessante durante a discussão disso na minha apresentação no Tech Talk. Quando você segue as boas práticas e implementa um protocolo conciso e claro, de certa forma podemos dizer que a implementação se “auto-documenta”. É algo que podemos traçar um paralelo ao que acontece ao utilizarmos Domain Driven Design. Aproximando a linguagem do código do domínio de negócio, facilitamos a compreensão da aplicação por pessoas que nunca a tinham visto antes. Uma boa arquitetura de web services declarativos (REST) fica muito mais clara do que uma arquitetura de web services imperativos (WS-*). Isto acontece porque com REST o que fica em destaque são os Recursos (que representam conceitos claros do domínio), em vez de Operações.

É claro que as pessoas ainda terão que ler um pouco da documentação, mas como os conceitos em sua maioria já estarão “no sangue”, as dificuldades iniciais são menores do que com WS-*.

O Felipe Gaúcho comentou no CEJUG sobre a capacidade de gerar clientes automatizados com WSDL. Embora isso seja verdade, no meu ponto de vista isso é meio que um mito. Não conheço ninguém que faça integrações automatizadas sem depender de seres humanos. A motivação disso é clara. Integrações envolvem regras de negócio, e ninguém que eu conheço faz negócios automáticos, sem definir as regras

Existia o mito de que as aplicações “descobririam” serviços automaticamente com UDDI e se virariam para fazer as integrações, gerando os clientes automaticamente. Embora isso seja tecnicamente possível, na prática isso pra mim é uma viagem que serviria mais para desenvolvimento de inteligência artificial do que para web services propriamente

Embora esta precisão do WSDL seja um ponto positivo, eu tenho a convicção de que a clareza que temos ao usar REST supera e muito as vantagens de termos geradores de clientes automatizados. Quanto a WS-* x REST de uma maneira mais geral, tem uma frase que eu gosto de utilizar. WS-* é apenas overhead a não ser que você tenha informações relevantes nos seus cabeçalhos SOAP. Se você nunca se preocupou MUITO (veja bem, MUITO) com o que está indo nos seu cabeçalhos SOAP, provavelmente um protocolo REST seria mais interessante.

Tem uma opinião a respeito disso? Estou ansioso para conhecê-la!

Java Magazine 56

Nos próximos dias chega às bancas a edição 56 da Java Magazine. Nesta edição saem 2 artigos meus sobre Web Services REST. Como vocês podem ver pela imagem, desta vez os editores me deram a honra de ser a capa da edição

Outra honra que tive no artigo maior foi a de contar com a excelente colaboração do Alexandre Bairos. Durante nossos trabalhos em cima deste artigo pudemos discutir com todos os detalhes as várias nuances dos serviços REST, com os quais já estamos trabalhando há alguns meses e estudamos já há um bom tempo.

O artigo maior é uma continuação dos artigos das edições 54 e 55. A proposta dele é pegar o exemplo dos serviços de leilão da edição 55 e implementar uma solução utilizando serviços REST.

A abordagem deste artigo foi implementar os serviços REST de forma que ficassem nítidos os principais aspectos do desenvolvimento desta linha de serviços. Tomamos a decisão de não incluir componentes sofisticados que pudessem tirar o foco do cerne do problema. Com isto, não incluímos componentes como o Jersey e o Apache Abdera, que por sua vez devem ter artigos na revista este ano.

O artigo pequeno é no formato “Quick Update” da revista. Nele eu falo sobre os principais projetos relacionados aos serviços REST e os principais acontecimentos nestes projetos. Esta linha de web services vem evoluindo bastante, e por trás disso estão muitos projetos interessantes.

Na minha humilde opinião o artigo maior desta edição é certamente o melhor dos artigos que já escrevi para a revista e acredito que ele pode contribuir como um bom ponto de partida no assunto. Este assunto é talvez o que mais me interessa atualmente, então caso vocês tenham opiniões, comentários ou críticas a fazer, estou aqui para trocar idéias

Java Magazine 55

Caros amigos, nos próximos dias chega às bancas a edição 55 da Java Magazine. Nesta edição sai um artigo meu entitulado “Web services WS-*“.

Este artigo é uma continuação do artigo da edição 54, na qual fiz uma análise dos web services REST e web services WS-*. Na edição 54, o foco era mais teórico, discutindo várias questões relevantes da implementação de web services nas 2 linhas de desenvolvimento.

Neste artigo, o objetivo é partir de um problema real de arquitetura orientada a serviços, e então realizar a modelagem e implementação utilizando a pilha WS-*. O exemplo adotado para contextualizar o problema é o processo de leilão do Mercado Livre, mas num contexto de leilão com apenas 1 usuário adquirindo um determinado item. O desenvolvimento foi feito utilizando o Apache Axis 2, uma das opções mais populares para o desenvolvimento deste nicho em Java.

Na edição 56, esta série será complementada com outro artigo prático, que utiliza a abordagem REST para resolver o mesmo problema proposto para esta edição. O objetivo com estes 2 artigos práticos é utilizar um mesmo exemplo que seja de fácil visualização por parte dos leitores e então descrever os detalhes principais do desenvolvimento de web services utilizando a abordagem WS-* e a abordagem REST.

Espero que os leitores gostem destes artigos e torço para que eles possam contribuir com o entendimento do desenvolvimento de web services, e mais especificamente, a implementação em Java. Ao longo do ano escreverei mais artigos nesta área, então se você tiver interesse no assunto, certamente recomendo acompanhar as edições futuras da revista

Atom: one format to rule them all?

Recently I’ve had several conversations regarding the Atom Syndication Format. This format is gaining more and more adopters and several big players in the industry are using it. Just to name the big boys, Google AND Microsoft are using it to implement RESTful APIs. When was the last time you heard Google and Microsoft agreed on something? This should hint that Atom is indeed a nice thing happening in our field.

Web services using the Atom format for data exchange encapsulate information using Atom’s standard elements and also define some extension points where needed. Some very useful elements are present in the specification. There are standard ways of publishing individual entries and collections, pagination support, links between resources, among other things useful for RESTful web services.

Depending on your domain model, the amount of data you would put in Atom extension points varies a lot. Some domains such as Google Apps can produce a RESTful model that uses a lot of Atom’s standard elements without needing to define too much extension points. However, if you use Atom to exchange billing information between ISP applications, you’ll probably have to define a lot of extension points. I’m saying this to show that some domains match much better to Atom structures than others.

While talking to Silvano (a very clever working mate of mine) a couple of weeks ago, he asked me if encapsulating everything inside Atom elements was not the same as encapsulating everything inside SOAP. This is a very very good question.

When you’re choosing a format for you data exchange in web services, it’s very important to analyse what you gain and what you lose by picking any given format.

For example, a good rule of thumb about SOAP services is: “WS-* is just overhead unless you have something meaningful in your SOAP Headers” (quoting Sanjiva Weerawarana at ApacheCon 2007).

Atom was designed in a RESTful manner by a very talented group of professionals. Many applications are making use of it to exchange data, and the adoption is growing fast. Could it be a silver bullet then?

That’s where I shall leave my observations. If you consider my example of billing information, you’ll see that most of the data there doesn’t mesh well with Atom’s standard elements. Thus, we’d need to define a lot of extension points, and wouldn’t make much use of Atom’s resources. Putting billing data inside Atom entries would represent an overhead without giving us much in return. In this case, I’d rather use my own XMLs directly over HTTP.

Am I saying that Google and Microsoft made a bad decision choosing Atom? No, absolutely not! Their decision was very good. Microsoft is using Atom for Windows Live API and Google’s using it for most of their applications. What do these have in common? They all manipulate web content. They have a domain where many things are accessible on the web, with lots of URIs, different media types, pagination, categories, tags, etc. Atom makes a lot of sense with web content.

I don’t think Atom is a Silver Bullet for RESTful web services in general. Of course you can choose to always use it, and benefit from the standards and the avaiable tools. But isn’t this true for SOAP as well?

What I do think is that Atom is very close to a Silver Bullet when you’re dealing with web content. Whenever you’re developing web services, choosing the right format for your data exchange is one of the most important decisions. To know well the avaiable options is very helpful, and certainly the Atom format brings a lot to the table when your domain meshes well with it. As long as you don’t think it’s the best choice for every application, go ahead and use it wisely

Microsoft também adere ao formato Atom para suas APIs

Depois de o Google passar a usar APIs RESTful com o formato Atom, agora é a vez da Microsoft começar a usar este formato. Ontem a empresa anunciou que as APIs do Windows Live serão RESTful e farão uso do formato Atom.

Após alguns anos investindo pesadamente em web services WS-*, parece que a gigante de Redmond está lentamente mudando sua forma de pensar em serviços web. É claro que durante um bom tempo eles ainda vão defender ferrenhamente o uso da pilha WS-*, pois eles não querem jogar fora os investimentos nessa área para a plataforma .NET. Contudo, é sem dúvida interessante ver que talvez o maior defensor de WS-* está mudando de direção, embora ainda não de forma integral.

Como eu já havia comentado algumas vezes, parece que a adoção de web services REST para diversos fins vai mesmo crescer rapidamente e ocupar um bom pedaço do espaço anteriormente ocupado por WS-*. E mais, eu acredito que os serviços REST vão crescer muito como mecanismo de integração de sistemas e plataformas. É bastante provável que o uso de integrações com EJBs e outras tecnologias que te prendem a uma plataforma específica caia de adoção. Especialmente em aplicações de internet, tenho convicção de que veremos um espaço cada vez maior sendo ocupado pelos serviços RESTful e que esta passe a ser a forma número 1 de comunicação entre diferentes aplicações.

O formato Atom tem muito a ver com esse crescimento, pois além do formato ser excelente para manipular conteúdo web, o protocolo AtomPub é um belo blueprint de implementação REST. Sempre que eu estou tentando definir um protocolo de comunicação REST e fico um pouco em dúvida sobre a melhor forma de fazer alguma coisa, minha primeira referência é o AtomPub. Estudar como eles resolvem problemas comuns no desenvolvimento REST te dá uma visão muito boa das opções disponíveis. Você já começa de um ponto de partida muito bom, e fica bem mais fácil elaborar um protocolo conciso e coerente depois que você conhece o AtomPub.

A propósito, quem quiser conhecer mais sobre implementação de serviços REST, recomendo fortemente a Java Magazine de Abril. Um certo sujeito vai publicar um artigo prático bem interessante sobre implementação destes serviços

Google Data API

I’m currently using Google Data API at work. This API offers RESTful interfaces for several Google services, such as Calendar, Picasa, You Tube, Blogger, Google Documents, among others. There are also client libraries for Java, C# and Python, but these are actually tools to facilitate, rather than new interfaces. All client libraries access the RESTful interfaces, so by all acounts the API is RESTful.

What I’d like to comment is how easy it was for me the to get up to speed with the API. There are several pages explaining the API’s features, the URIs, their use of HTTP method, return types, etc. Their design is pretty much compliant to all REST best practices (although they do use some query string parameters ocasionally). Being very familiar with this kind of web services, most of what I did was looking and saying: “Ok , this is how i expected it to be”. And after less than one hour I was ready to begin using the API properly.

Worth noting is that there were no “Interface Document” to look at. Not anything similar to WSDL or any other IDL. What was there was just a simple and RESTful API that was pretty easy to use after you knew what the resources were and which operations they support. Several pages describing their protocol and the XML entities they use were enough for me to know how I was supposed to integrate with a reasonable amount of their services.

I don’t even want of to think of how would it be if they had WS-*. Just to read the WSDL documents would take me more time than to read all their RESTful documentation. There would be a lot of operations and messages described in their WSDLs, and it’d be a massive reading to get the grasp of the API.

Fortunately Google (the most powerful web company) is embracing a RESTful design and it should probably take many other companies with it. They’re also supporting the use of Atom and Atom Publishing Protocol, so many nice things should keep coming. Apache Abdera is already integrating Google Feed Server code, and hopefully we’ll be able to use Abdera for most of Google’s services.

Very very nice! By the way, I took a good look in the source code of Google Data API and it’s very well implemented. They have a very interesting approach to manipulate feeds and entries. It makes it very easy to model a lot of stuff using just feeds and entries. It was an inspiring code inspection and I’m thankful Google also embraces open source These guys are good!

Java Magazine 54 - Meu primeiro artigo

Caros amigos, é com enorme satisfação que anuncio que esta semana chega às bancas a edição 54 da Java Magazine, na qual estou publicando o meu primeiro artigo.

No artigo desta edição, faço uma análise imparcial dos web services REST e web services WS-*, dando uma visão pragmática do nosso momento atual de implementação de web services.

Este é o primeiro do que eu espero que sejam muitos artigos meus publicados na revista, e pelo menos inicialmente a maioria deles será na área de web services. Espero que bastante gente leia o artigo e possivelmente dê opiniões sobre o mesmo. Torço para que vocês gostem das minhas publicações, vamos ver se eu levo jeito para a coisa

Diversidade de tecnologias

Eu tenho postado com alguma freqüência sobre o que vem acontecendo no desenvolvimento das tecnologias dos web services Restful.

Este fim de semana o James Snell implementou um adapter do Apache Abdera para o CouchDB. Este adapter permite que se consiga facilmente implementar um armazenamento de dados no formato Atom com uso de uma instância do CouchDB.

Como eu já mencionei anteriormente, o Abdera oferece uma API para manipulação de conteúdo no formato Atom e a realização de operações do Atom Publishing Protocol. Já o CouchDB é um banco de dados orientado a documentos que é escrito em Erlang e foi projetado para extrema escalabilidade e permite fácil instalação em servidores com múltiplos núcleos ou em clusters de máquinas.

Em vez de utilizar tabelas com colunas (como os bancos de dados relacionais), o CouchDB armazena os documentos em formato JSON e disponibiliza como interface uma API Restful, com clientes já implementados em várias linguagens, como Javascript, Java, PHP, Ruby e Python.

Acho que isto expressa muito bem o horizonte que vem se formando. Em vez de pilha de tecnologias e protocolos proprietários, temos diversas tecnologias e plataformas diferentes conseguindo se comunicar através de HTTP. Um projeto open source Java que manipula conteúdo Atom já disponibiliza com facilidade um mecanismo de integração com serviços REST que manipulam dados em formato JSON.

É impressão minha ou estamos de fato vendo rapidamente uma mudança radical de abordagem na vanguarda da tecnologia? A mesma IBM que antigamente dominava de forma absoluta todo o mercado de hardware e software com soluções proprietárias agora patrocina diversos projetos open source e mantém sua elite intelectual trabalhando nestes projetos.

Soluções open source estão liderando várias frentes de desenvolvimento e com isso rapidamente surgem integrações entre componentes feitos em diferentes linguagens e plataformas. O conhecimento não está mais guardado a 7 chaves, e sim discutido abertamente por uma comunidade que aceita qualquer um com capacidade para agregar idéias boas.

A criatividade e a iniciativa individual nunca tiveram tanto poder, e isto é fabuloso. Com isso, claro que a versatilidade e o conhecimento diversificado ficam muito valiosos.

Hum… maybe it’s time for me to fight my disgust for Javascript and start developing something nice including JSON

JSR-311: Java API for RESTful Web Services

Eu estou atualmente implementando alguns web services Restful, e estou avaliando opções para alguns pedaços do desenvolvimento. Eu já sabia que existia uma JSR para web services REST, mas ainda não tinha lido a mesma.Agora há pouco li a JSR-311, que definirá padrões de implementação Java para uma API Rest, do lado do servidor. A parte de implementação de clientes será tratada em outra(s) JSR(s) .

Esta JSR é bastante interessante, e já pude ver nela o tratamento de coisas muito úteis. De principal destaque para mim está a abordagem de mapeamento de URIs em recursos e métodos e a questão do mapeamento de classes Java para dados com diversos content-types.

Em relação às URIs, há a definição de regras para mapear URIs em classes e métodos, instanciando as classes necessárias e invocando os métodos adequados. Suponha por exemplo uma requisicao HTTP PUT na URI /usuario/16728/produto/228/configuracao/. Em um protocolo definido por mim, isto representaria uma atualização nas configurações do Produto 228 para o Usuário 16728. Um ser humano consegue entender isso sem tantos problemas, mas uma implementação manual destes mapeamentos e o parsing dos parâmetros podem ser coisas bem trabalhosas. A JSR 311 utiliza várias annotations para conseguir definir o encadeamento de classes e métodos a partir da URI utilizada, e isto faz com que você consiga desenvolver em Java normalmente e ter as suas classes instanciadas e invocadas com URIs tão flexíveis quanto você queira. Muito bom ter isso como recurso, pois implementar na mão é bem trabalhoso.

Outra coisa muito interessante é a maneira de mapear classes Java para diversos content-types. Isso é algo fundamental para uma implementação Restful com bastante flexibilidade E possivelmente alta performance. A idéia por trás disso é que o servidor recebe uma requisição de um cliente e verifica quais são os content-types que o cliente aceita. Com base nestas informações, o servidor escolhe a forma que irá utilizar para transmitir os dados.

Suponha por exemplo que uma aplicação PHP está se comunicando com seu servidor, e ele lhe informa que aceita os content-types text/plain, text/xml e application/json. O servidor pode escolher qual formato utilizar para o envio e possivelmente o envio com formato json facilita bastante a aplicação PHP. Este mesmo servidor pode receber requisições de uma outra aplicação Java, que preferencialmente receberá do seu servidor um stream binário, que terá a melhor performance de todas as opções.

O uso desta abordagem dos mapeamentos em content-types permite que sua aplicação tenha ao mesmo tempo alta interoperabilidade e alta performance. Você conseguirá se comunicar com várias plataformas e aplicações diferentes, e continuará tendo a opção de alta performance, caso seja uma aplicação da mesma plataforma. Você não consegue isso com web services WS-*. Eles não têm tamanha flexibilidade.

O meu próximo passo agora será analisar com detalhes o Jersey, a implementação de referência desta JSR. A especificação em si ainda está um tanto crua, pois ainda é um early draft. Já pude ver vários pontos interessantes, mas a definição ainda está sujeita a muitas modificações. Vou avaliar agora o que o Jersey já oferece e torcer para que ele já tenha componentes fáceis de usar e flexíveis. A proposta dele é excelente, vamos ver se a implementação consegue oferecer estes recursos sem amarrar muito as decisões de projeto.

Atom feeds for enterprise application messaging

In the last months I have studied and worked a lot with web services in general, and more specifically the RESTful ones. I believe we are going through a fast maturation process in this area, and RESTful web services are becoming the preferred choice for many new implementations. Right in the thick of things in this field is the Atom Publishing Protocol. This is the blueprint solution for RESTful web services, and its adoption is growing fast, reaching much broader scope than just blog applications using the Atom Format.The Atom format and AtomPub protocol can both be used for many interesting purposes. This year I’m working on a big refactoring (actually a new implementation) of a widely used Globo.com application. This application (let’s call it Register) is responsible for the creation of new users and provisioning new services to them, among other features.

A nice concept present in the original development is the use of Application Connectors. Through these connectors, other applications get notified of events that happened in the Register application. An example is: when a new subscriber (a paying user) is created, a connector sends the notification to another application in order to create the subscriber’s mailbox in the company’s external mail provider. Another example is: when a user gets provisioned in the blogging service, another connector sends a notification to the blogger application, that does what it needs in order to create the user’s directory and quota on the file server.

Although i like this concept, it currently has some problems. This connector’s invocation is done explicitly by the Register application. The Register application knows that a new subscriber must receive a new mailbox, and it needs to call a given connector to do this. This is my biggest concern with the current implementation. I strongly believe that an application that creates users must not know anything about mailboxes. In the current structure, when a new application ABC must be notified of events in application XYZ, application XYZ must be modified to invoke a new connector. This doesn’t please me at all. Let me explain a solution that pleases me more

To explain my idea, I’ll propose some examples involving Google and its services. As we all know, Google offers several different services, all of which can be accessed using the same Google account. When you register at Google, you receive a mail account. Let’s suppose that Google Register application sends a new entry to an Atom feed every time a new user is created. This way, every user creation is present on the Atom Feed. If an application (for example Google Mail) needs to be notified of the creation of new users, it just needs to subscribe to the Register’s Atom feed.

Let me propose a richer example now. Let’s say Google starts to offer some super cool software development services. If you’re a developer, you can ask them to give you a “development account”. This development account would give you access to a Subversion repository, a Bugzilla project and a MySql database. Each of these would be an independent service offered by them, subject to change at any given time. The activation of “development accounts” could also populate an Atom feed.

This way the Subversion, Bugzilla and MySql services could be subscribers of the feed, doing everything they need when a new development account is activated, in asynchronous manner. The application that activates the development account has no knowledge of any other services. If Google wants to offer new services such as a Maven repository or a Continuous Integration environment, no problem. The new services would just subscribe to the Atom feed and do whatever they need when a new account is activated.

If Google wants to offer a free development account and a non-free account with better features, there could be another Atom feed for the activation of the paying accounts or maybe updates to the same existing feed. The Register application would know only about registrations, and other components could be easily plugged and unplugged from this process, without modifications on the Register application. Ah, and worth mentioning… totally decoupled from any specific platform. I don’t know how to implement any kind of messaging more decoupled than that.

This is much much better than the way our Register application sends notifications currently. And I’ll be pretty happy once we manage to do this, it’ll be so cool!

By the way, these Google’s software development services would be awesome. My friend Bairos kindly provides me Subversion and Trac services, but he doesn’t have Google’s bandwidth Let’s hope Google gets to know about this and starts offering these services. It’d be amazing!