The Power of REST – Part 3

Last week in The Power of REST – Part 2, I talked about how investing effort in backward compatibility and having flexible settings, it’s possible to avoid a lot of “API versioning”, something Roy Fielding has decried. In this article, we’ll look more closely at the depth and power of hypermedia.

How does the web do it?

Let’s remember that REST is about bringing the scaleable power of the web to APIs. One of those classic features is “Hey, go to XYZ.com, click on ‘Books’, then click on ‘Fiction’, then click on ‘The Job’ and you can get a free copy.”

Recognize this pattern? No one can remember long URLs, but we all know about following a chain of menu items based on the shorthand text.

Hypermedia is providing links all along the way. We sometimes refer to this as a “discoverable” API. I once likened it to the classic ZORK text adventure, where you have a confined set of moves, yet can explore a very complex world.

When clients hard code URLs, updates become brittle. Everyone knows this, otherwise there wouldn’t be things like a CORBA Naming Service subspec. So when I see tools that not only support but advocate full focus on URIs, I cringe. This isn’t what REST is about.

Migrating a service

Imagine we had started things out with a service used to manage supervisors. It was basic, perhaps a tad crude. Maybe we were wet behind the ears and didn’t totally grok REST. Not a lot of hypermedia. But eventually, we migrated to a newer “manager” service.

The good news with hypermedia is that we can continue to serve data at the old URI:

If this fragment was served under the old URI, /supervisors/1, old clients could access the data found there. But with a push toward hypermedia consumption, they could navigate onto the newer version of things.

This legacy representation can be put together by the newer “manager” service to support the old clients.

This route, served to the old URI by the “manager” service, can actually retrieve information in the newer format, and repackage it as a legacy “Supervisor” record. But by supplying up-to-date links, we provide an on-ramp for clients to migrate.

Assuming we had shutdown the old “supervisor” service, the following DTO could nicely sustain the old clients until they were ready to move on up.

This immutable value type can take the new-and-improved “manager” object and extract the older representation smoothly.

Don’t argue the wrong end of things

I’ve seen a particular argument pop up in favor of REST many times. It brags about how links can change without impacting clients. Frankly, that argument comes across as lame and weak. That’s because it’s NEVER presented under the guise of backward compatibility. It’s kind of posed in a vacuum.

Building REST resources with full focus on backward compatibility, supporting old URIs and old formats, is a much stronger message in my book.

SOAP and CORBA weren’t designed to let you slip in an extra field here and there. At least, not without massive effort. It’s why no one ever did. Can you imagine going into an IDL/WSDL file and attempting to “slip in” an extra field to ease migration? It’s almost incomprehensible.

But with Jackson and robust principles applied, it’s easy to update a given route with additional data that can easily support two different clients. One REST resource supporting two clients: THAT is a strong argument. Not “links can change”.

Don’t preach it, use it

It’s why I’m giving you a sneak peek at something I’ve been wanting to write for about three months. I find myself attempting to explain the same concepts about REST on Twitter, at meetups. In Berlin, I ran into a dear friend that pinned me down and asked me hard questions on REST for over an hour. Bring it on! That affirmed my gut decision to create this:

This repository contains several REST-based scenarios and how to implement them with Spring HATEOAS. It’s not complete. It hasn’t even been “publicly” announced, but it gives me a concentrated place to show how REST works compared to RPC-over-HTTP.

The numerous times I’ve watched Oliver defend REST, I too and picking up the banner and striving to help spread the word that if we can adopt HATEOAS and link-driven flows, we can build more sustainable systems.

For a little something to chew on, I’ll close this article with the following tweet.

@tfnico#Swagger is a no-go if you’re into hypermedia, so it’s the HAL browser… If you don’t care (which is fine) go with Swagger…