Twenty-five years, and I don't look a day older than one! Alas, I can't say the same for my Travelling Companion. I spend most of my time inside a book (well, duh) while the TC sees the world. Read all about me and follow my blog posts to share my experiences as bookmark and travelling worm.

From time to time, I'll say something meaningful. Like a t-shirt.

Today’s travel notes

The Travelling Companion has been rather sedentary recently, so I've been crawling through her photo albums again. I came across some pictures of Holland and some scraps of a letter that she wrote about her encounters with dikes.

This letter is twenty years old, written in April 1988. I thought you would enjoy a bit of ancient history :)

We drove along a very impressive dike, which separates the Markermeer from the IJsselmeer. The dike is 29 km long. It is quite lovely to see the open water on each side of the road, with yachts and water-birds dotted all over. A large area east of the Markermeer is reclaimed land, called a polder. There was a plan to reclaim the entire Markermeer, so the dike was built to allow the land to be drained. But evidently they have decided not to do that just yet. One reason why they need more land is that the airport Schiphol is too busy. So they planned to build another one where the water is at present.

North-west of Amsterdam is another polder, eight metres below sea level. There is a canal connecting Amsterdam to the North Sea, and the water in the canal is at sea level. So the canal is well above the level of the roads! It is a very odd experience to see a ship sailing by above you.

A tall tale

Many people have heard the uplifting story of brave little Hans, a Dutch boy who saved his country by sticking his thumb in hole in a dike, to plug an incipient leak. It's a ridiculous story, really, when you see the size of the dikes.

When the TC was in the Netherlands, she mentioned the tale to a Dutch friend, fully expecting him to acknowledge it as a piece of native folklore. He looked faintly amused and said that he had heard the story but thought it was probably English or American, because no Nederlander would come up with something so silly.

Traveller's tip

Don't believe everything they tell you.

The book I’m in

RESTful Web Services, by Leonard Richardson & Sam Ruby.

Technically tranquil.

The photos

Climbing up a dike, somewhere in the Netherlands:

Due to a lamentable lack of labelling (notice the skilful alliteration) I can't tell you exactly where the TC was when she snapped these shots, except that she was in Holland and on a dike.

To be precise, I can't even be certain that she was in Holland itself. This may be one of the other provinces of the Netherlands, such as Zeeland.

The view from the top of the dike:

If anyone recognises the dike, or the storm surge barriers in the distance, let me know.

That’s all for today, dudes.

Caros amigos, na terça-feira dia 27/05 farei uma apresentação sobre web services REST no RioJUG.

Esta apresentação será semelhante à que fiz recentemente na Globo.com, mas acho que ficará um pouco melhor. Maiores informações sobre a apresentação podem ser vistas na página do grupo. Após a apresentação atualizarei este post colocando os slides.

Quem quiser/puder comparecer será muito bem-vindo ;)

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! :)

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

I said before that I don't like query strings in RESTFul URIs. You cannot cache the results in the web server and in many cases they lead to a poor design of your URIs.

However, there are cases where query strings are useful and make sense. In the project I'm working right now, we have an asynchronous queue which several server instances consume periodically. This queue has events that must be processed, and each event belongs to a given user. Each user may have several events in the queue.

We have this queue of events that must be processed and we register them in another list when they are successfully processed. When an event is processed, he goes to the "processed" list if everything goes right or he stays in the queue if something gone wrong. In the queue we register how many times we tried to process each event.

In my team we have an application that helps us manage our infrastructure. This application does many things that we previously needed to ask to the operations team or DB team. Something very desirable is to be able to check how the queue is going without needing to check server logs or the database. So we're adding some features in the management application to help us check the queue.

Ok, now let's talk about the RESTful services. We've implemented some services that access the queue. One the of services allows us to check how many events are still in the queue with at least N tries. For example, how many events are pending with at least 1 try?

What's the Resource here? In my opinion the resource is "Pending event". Considering this, I would access this resource doing GET /event/pending. Ok, but doing GET /event/pending would probably give us the whole list of pending events. I want pending events with at least 1 try. How can we do that? We could do a GET /event/pending/1, and it would work. However, this URI is bad, very bad. If I didn't know what this service was about, I'd probably say this URI returns the first pending event according to some order. Probably it would be the oldest or newest one.

So how do we form this URI? We could also have a GET /event/pending/tries/1. This would indeed be much better than the first URI, but I don't like it either. My resource is "Pending event". Pending events with at least 1 try are still just pending events for me. What I want is just to filter the pending events. So, I ended up using GET /event/pending?t=1. "t" in this query string stands for "tries". I could also have used GET /event/pending?tries=1. As a matter of fact, I think supporting both is nice. It would be similar to command line options in Unix applications.

Now, let's say I want to know the pending events of a given user. Looking at the previous URI, You might say GET /event/pending?u=123 or GET /event/pending?user=123. But in this case, I wouldn't use query strings. The best URI in my opinion is /event/pending/user, and that would lead to GET /event/pending/user/123. What's the difference here? I consider the "User" as a meaningful thing. It's another resource. However, "number of tries" for me is just a filter. I don't need to know anything about a specific try, so it's just a filter in this case. Another similiar filter would be "Pending events created before today". We could have another query string parameter to filter events by creation date. Something like GET /event/pending?c=03/04/2008 or GET /event/pending?creation=03/04/2008.

So, I changed my mind a little bit about query strings. They are indeed useful in some cases, such as this example. They are good to filter results. Filter by something that it's not a resource. To decide our URIs we must always think of what's really a resource in our application, and what's just a filter. Such as in the world wide web, URIs identify Resources. After deciding what's a resource and what's just a filter, we can design our URIs much better. Meaningful URIs are among the most important things in RESTFul web services.

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!

Go to Section 2.5.  If you have a Safari Bookshelf subscription, it's here.