Re: How much REST should your Web API get?

Jan,

I agree with you on the importance of fully understanding and exploiting
the power of a paradigm first, before attempting to define a new one.

I think that the influence of REST on the design of so-called "web
services" has been extremely positive and enabled a simpler,
resource-oriented and more effective "Web API" style to emerge for
machine-to-machine interactions. This style can't eclipse REST as it
doesn't address the same requirements even though some are shared.

> What does that mean: "and what makes it so powerful to scale the web of
hypermedia documents"?

I'm just considering how powerful it is to have a universal user agent (a
web browser) that can display and interact with HTML documents distributed
over the internet, without having to recompile the browser to access each
web site (true uniform interface composed of the URI/HTTP/HTML trio plus
additional standards such as JS/CSS/PNG). There is a deep independence of
evolution between clients and servers, even though they do need some level
of compatibility (HTML 5 support for example).

> It just not as simple as taking half of REST and getting half the
benefits. REST works as a whole, not in 'layers' or 'levels'.

I agree, the whole is more than the sum of its parts. However, if you look
at the HTTP protocol itself, it also continues to evolve towards better
network efficiency, asynchronicity and more real-time interactions:
http://tools.ietf.org/html/draft-ietf-httpbis-http2-02

The Web clearly isn't "just" a set of hyperlinked HTML documents anymore.
Web APIs, push techniques such as WebSockets are other illustrations of the
new requirements expressed by web developers.

> Now, there is quite a difference between a sensor and a mobile app. Who
says a mobile app cannot have hypermedia capabilities?

Even though, mobile apps can have hypermedia capabilities, we can't ignore
that the majority of mobile apps out there just aren't regular HTML web
sites, and for many of them for good reasons.

Think of a mobile games or mobile apps with an admin UI but running a
background service, for example to regularly sync data with a back-end (ex:
iCloud). In those cases, it makes little sense to consider this
machine-to-machine interaction as an application of hypermedia.

> And who would make a sensor a REST client? I'd rather have the sensor
send measurement data via, e.g. UDP.

I was thinking about smart sensors such as the Nest connected thermostat.
It does use a semi-private web API that could be improved to become much
more resource-oriented:
http://www.wiredprairie.us/blog/index.php/archives/1442

> Hmm, can you be more specific about what you mean here?

When you setup an IFTTT rule, you don't want the web APIs that are used to
change overnight without proper coordination and control of their update.
This requires out of band communication and it rarely done properly today,
but this can't be solved magically just because you put hypermedia into
play.

> I'd say, the vast majority of Web APIs fails to be RESTful because people
simply did not follow the style.

I would say that the vast majority of Web APIs can never be RESTful because
they don't fully fit into the REST requirements.

> Show me a single example that has been deliberately designed  unRESTful
on the basis of design principles. To me this is just the same old
discussion over and over again: People make a (rather unedcuated) claim,
mistake that for truth and come up with suboptimal design.

I gave a few examples above. My turn to ask you for an example of a proper
RESTful web API (beside HTML web sites, RDF driven Linked Data and
Atom/AtomPub driven blogs) exclusively using hypermedia (HATEOAS) to
interact with it (not just hyperlinks).

> And that is not only true for wanna be REST services, unfortunately it is
an all too common way to approach all sorts of IT problems.
> In my experience, people learn best if we do not settle for 'premature
agreement' but use, for example, a style to foster more flexible thinking.
Usually, whoever endures that process is thankful in the end.

I agree with that and I think that a proper/formal "Web API" style could
help in this regard.

> Either way, a native app makes a perfectly RESTful client if you design
it that way. Personally, I'd go a very long way to maintain the benefit of
not having to coordinate client deployment with API changes....

If you look at how mobile app discovery is currently working, if you are a
company making a living out of it, you certainly prefer to go through the
formal app store deployment procedures that just hoping people will browse
the web from their smartphone screen like they do on a desktop. Maybe HTML
5 will change that landscape in the coming years, but many people will
prefer a different UI paradigm for their mobility use cases.

> What is a "rich hypermedia client"?

Sorry, I meant when a rich hypermedia client ISN'T available. I meant a
modern web browser running on a connected watch might not be the best idea.

> Can you be more specific about the situation that seems to be the root
cause for the perceived need that you have to change the style?

I hope I gave enough explanations above.

> Can you explain what you mean by "a dynamic way like HTML is used by web
browsers"?

That web browsers don't need to learn or be redeveloped/recompiled each
time a new web page/site is published, contrary to Web APIs.

> To me it remains unclear what the problem is you are trying to solve.
Please explain, I'm all ears.

I'm just acknowledging that there are many cases (look at the catalog of
9000 public web APIs on PW) where the hypermedia/uniform interface
constraints of REST just doesn't fit with the requirements. You can't just
ignore that reality and consider that all those smart developers are just
plain wrong because they didn't read/follow the REST style properly/fully
(many books and presentations exists and most developers are doing their
best, and there is much tooling available now).

This isn't to say that all those APIs can't benefit from a better
resource-oriented design (instead of a RPC inspired design) and usage of
HTTP features, but pushing REST too far why a systematic hypermedia
constraint is just counter-productive in my opinion.

Best regards,
Jerome



2013/5/2 Jan Algermissen <[email protected]>

>
> On 02.05.2013, at 19:48, Jérôme Louvel <[email protected]> wrote:
>
> >
> > Jan,
> >
> > I remain a strong proponent of the idea that it is more fruitful to aim
> at rethinking the problem to fit a sound paradigm rather than to blame the
> paradigm for not fitting the problem (one's perceived view of it, that is).
> >
> > But when the paradigm isn't intended to solve a given problem, do you
> think we should force the problem to fit into the paradigm?
>
> No, certainly not. What I am arguing against is what I experience so
> often: That people claim some paradigm is a bad fit for a problem instead
> of thinking thoroughly through the problem until they can make an educated
> choice.
>
> >
> > REST was never designed to solve all software architecture problems.
> That's quite the opposite and what makes it so powerful to scale the web of
> hypermedia documents.
>
> What does that mean: "and what makes it so powerful to scale the web of
> hypermedia documents"?
>
> >
> > Two concrete points:
> >
> > I don't buy the efficiency argument regarding discovery and granularity
> of messages - unless you ignore caching and the possibility to tailor
> representations for specific devices.
> >
> > You could also add HTTP compression to the mix. I'm a fan of HTTP
> caching and content negotiation as well. The "Web API" style proposed fully
> leverages those features.
>
> It just not as simple as taking half of REST and getting half the
> benefits. REST works as a whole, not in 'layers' or 'levels'.
>
> >
> > You write about the 'Web API style' "requires coordination between
> clients and servers when changes are deployed" - doh... this eliminates
> *the* (**the**) primary benefit to apply REST.
> >
> > Exactly, but if you ship a native mobile app or a connected hardware
> device with no hypermedia capability at all (think about a dumb sensor),
>
> Now, there is quite a difference between a sensor and a mobile app. Who
> says a mobile app cannot have hypermedia capabilities? And who would make a
> sensor a REST client? I'd rather have the sensor send measurement data via,
> e.g. UDP.
>
> > you definitely need to coordinate the clients and servers even though
> you are fully and properly using HTTP.
>
> Hmm, can you be more specific about what you mean here?
>
> > This is why the vast majority of so-called web APIs are versionned and
> based on stable URIs and representations structures. They can't always
> afford to dynamically discover the user interface.
>
> I'd say, the vast majority of Web APIs fails to be RESTful because people
> simply did not follow the style. Show me a single example that has been
> deliberately designed  unRESTful on the basis of design principles. To me
> this is just the same old discussion over and over again: People make a
> (rather unedcuated) claim, mistake that for truth and come up with
> suboptimal design.
>
> And that is not only true for wanna be REST services, unfortunately it is
> an all too common way to approach all sorts of IT problems.
>
> In my experience, people learn best if we do not settle for 'premature
> agreement' but use, for example, a style to foster more flexible thinking.
> Usually, whoever endures that process is thankful in the end.
>
> >
> > You could say that native apps aren't needed and could be re-developped
> as HTML 5 apps, but this isn't always possible or desirable.
>
> Either way, a native app makes a perfectly RESTful client if you design it
> that way. Personally, I'd go a very long way to maintain the benefit of not
> having to coordinate client deployment with API changes....
>
>
> >
> > Aside from systems that focus on sending fine grained control messages
> around in (near) realtime, I have yet to see a case where REST does not
> shine due to performance, scalability and the ability to decentralize
> management of the deployment and release cycles.
> >
> > Again, my point is to take the best of what REST brings but not try to
> apply it in cases where a rich hypermedia client is available,
>
> What is a "rich hypermedia client"? Can you be more specific about the
> situation that seems to be the root cause for the perceived need that you
> have to change the style?
>
> > but isn't so uncommon. I'm just trying to do REST justice otherwise
> we'll get a backslash when people finally realize that the vast majority of
> REST endpoints/APIs/etc. can't be used in a dynamic way like HTML is used
> by web browsers.
>
> Can you explain what you mean by "a dynamic way like HTML is used by web
> browsers"?
>
>
> To me it remains unclear what the problem is you are trying to solve.
> Please explain, I'm all ears.
>
>
> Jan
>
>
>
>
> >
> > Best regards,
> > Jerome
> >
> >
> > 
>
>