« Resource Profiles and Types | Main | API Maps: Hypermedia API Design »

Saturday, August 06, 2016




Thank you for the blog post, I'm starting to understand the benefits of hypermedia :)
I do have one question. The blog mentions that clients are unaware of service boundaries if they follow a link of a next step. But as I understand these next steps are represented by a link with rel and href.
From a micro service approach, if a response from service 1 contains a link to service 2 does this not create coupling between the two services?


thanks for your comment, @tim. and yes, you're right that a link between two services establishes some kind of coupling. that's because when you follow the link, you now interact with the linked resource. you could classify this kind of "coupling" as "choreography", where interactions lead you step by step. that would be different from more classical "orchestration" approaches, where you have a single grand plan and that's what you follow (if you're interested in the different ways in which you can look at "coupling", http://dret.net/netdret/docs/wilde-www2009-loosely-coupled.pdf is a paper cesare pautasso and i wrote a while ago).
the neat thing about REST hypermedia is that it makes "decentralized choreography" a natural part of the design and interaction model. and because it is stateless, meaning that each request is completely self-contained, you are able to choose between steps if there is more than one available.
let's idealize a bit here: let's assume you have shopped and now you have three options to pay. the shopping service is "coupled" to these three payment services in the sense that you probably will pick one of these three, based on your preference.
in a perfect RESTful world, though, your shopping service would expose a "user x with shopping cart y needs to pay z dollars" resource, and you could even pick a non-affiliated payment service, as long as that service would be designed to work with these "i am x and have order y for z dollars to pay" representations, and your shopping service would expose this kind of resource and also provide a payment protocol for that other service to make the payment.
now that may be a bit of a stretch here, in particular because payment is such a sensitive area, but maybe it highlights a bit what the hypermedia coupling does, but also where well-designed hypermedia APIs allow clients to opt out of them, when clients don't want to use the provided hypermedia controls.

Peter Rushforth

Nice post, thanks! I think it's worth mentioning too the emphasis on hypermedia format that REST implies, which I (often) find sorely lacking among REST advocates' discussions. You do properly allude to it in the post (e.g. 'self-descriptive') , but it is often overlooked and sometimes misrepresented. For example I've often read that a "good" REST API does not need documentation - a statement which I take issue with, since the specification/documentation of the _format_ (s) is definitely part of the "in band" information that one needs to write a client for such an API.

Also, I am not sure that statelessness implies that the server will still be in the same state after your vacation. I think it means that one need not have performed some session initiation per the protocol used, but I would like to learn more about that aspect anyway.

All the best


thanks for your comment, @peter! i absolutely agree that "self-describing" does not imply "no documentation". and that's not what REST means by that term. it simply means that you don't need out-of-band information to act on a message. when it comes to documentation, which one of the basic Web Concepts (http://webconcepts.info/concepts/) you are using already is a very good starting point. but then you still need to document your media types and any non-standard concepts you're using. the API documentation space still has a long way to go!
about the vacation example: your *client state* goes on vacation, too, but not the *resource state*. let's assume you browsed a library and asked about the available copies of a book. your result showed three books, and then you went on vacation. when you come back, maybe not all of those three books are still available. but your client state assumes they are. so you click on "reserve", and then the server responds with "this book is no longer is available". this is why REST clients have to be able to deal with failure *at every single step*, because this scenario can happen anytime.


Very valuable post. Thanks.
Currently I have to do some decisions about REST services versioning. There are many post about this, BUT I still do not know what to do.
It seems that there are at least 2 camps:
URL versioning versus HTTP Header Versioning (content negotiations, etc.).
I tend to key URL's stable over the time, BUT I am really not sure, especially in the context of large-scale integration.
Could you please elaborate on the REST versioning topic?


thanks for your comment, @jan! me and my colleagues at the API Academy often joke that we should have a one-slide workshop on API versioning with the one slide saying: "DON'T!"
of course that's not terribly helpful, but it really is what you should be striving for. as a follow-up to http://dret.typepad.com/dretblog/2016/04/robust-extensibility.html i am planning on writing in more detail on how to design APIs this way. the key point really is to design in a way that you don't need to version; all you do is evolve, and there's no need for version labeling at all. if you do reach the point where you make non-backwards-compatible changes, you start breaking the ecosystem and there's no need to call this "versioning" anymore: you're creating a new thing and the main/only reason why you might want to keep the name is branding.
for now, i highly recommend to read mark's https://www.mnot.net/blog/2012/12/04/api-evolution which touches on all these points, and also highlights the fact how using web architecture makes you think about versioning in a very different way.


Hi dret
Many thanks for your reply on my comment.
In the meantime I 've read a lot of stuff (books & links) about REST versioning including those you are pointing to.

After all it looks like we should use the term 'REST versioning' in the sense of Semantic Versioning MAJOR version only, i.e. we should not talk about REST Versioning unless your API is moving to the nexr major version, right?

In this sense if you say DON'T (version REST URI) are you stating: Stay with your stable URL as long as you can, and only version URL if you have to brake the backward compatibility of the service?

In my current working context we have the following integration challenges (as many other big companies might have):

1) REST clients/consumers can be 'machine', i.e. another service, OR web browser user, OR native application (e.g. iOS) user.
In this case how do you handle e.g. mandatory input fields changes? And these changes MUST be validated in some backend layer?

2) Incremental support (providing semantically new version of a service) for e.g. pilot user group ?

3) Support for the user groups in different regions not all at the same time?

4) Major service change as incremental rollout?, i.e. no big bang deployment!

Could you please elaborate little bit on each of these topics/questions?

The comments to this entry are closed.