Hi,



I've been reading a lot about how to do "proper" REST this week and the more I

read, the more I'm lost, especially the HATEOAS part I fear.





First, to give some context, the company I work for develops mobile applications

for clients.  Most of the time, they want to get an iPhone native application,

an Android application and a traditional Web based Application to cover the

other mobile phones out there.



The way we are currently doing things is the good old (bad?) RPC over HTTP way. 

We define a bunch of URI which are coded inside the different apps, we exchange

data as JSON, etc.  This week, trying to do things in a better way, I've begin a

more serious study of REST and how to do it properly.



What I really can't wrap my head around is how, technically, have HATEOAS in a

native application?  I mean, when building a native application, I have tables

to display lists, buttons to do some things, etc.  My understanding is that all

those should be displayed based on the data (hypermedia) received from the

server.  Is that right?



A concrete example would be a hotel room rental service.  The person would open

the application and have fields to enter the from/to dates.  It would then tap a

"Get Available Rooms".  The app would call the server and get back a list of

rooms along with prices and other details.  From there the person could select

one room and rent it.



The RPC way of coding this is obvious to me but I have no idea how I'd do that

in a proper REST way!  What bugs me is that every way I look at it, the client

application would still be tightly coupled to the service.  I understand how I

would only need to GET the http://rent-a-room.com URI hardcoded and then in the

response I would have the http://rent-a-room.com/available-rooms URI given.

But...  My application would expect each "call" to return some pre-defined data

and "rel", those can't appear out of the blue?!



I guess what I'm trying to say is that both the business process and the data

exchanged must be known to my client application at the moment of coding it, and

those can't change without breaking existing clients.  But reading about REST,

every is talking about loose coupling and not breaking clients... I just don't

see it.



What am I missing?



Thanks a lot and sorry if it is a stupid question!

>>>>> "Daniel" == Daniel Roussel <daniel@...> writes:



     Daniel> Hi, I've been reading a lot about how to do "proper" REST

     Daniel> this week and the more I read, the more I'm lost,

     Daniel> especially the HATEOAS part I fear.



There are levels of REST, so I suggest you don't worry too much about

HATEOAS.



Using properly named urls and verbs will already give most of the

benefits.





     Daniel> I guess what I'm trying to say is that both the business

     Daniel> process and the data exchanged must be known to my client

     Daniel> application at the moment of coding it, and those can't

     Daniel> change without breaking existing clients.  But reading

     Daniel> about REST, every is talking about loose coupling and not

     Daniel> breaking clients... I just don't see it.



     Daniel> What am I missing?



     Daniel> Thanks a lot and sorry if it is a stupid question!



It isn't, but I myself don't worry too much about this. If your URLS

are stable, and you provide redirects, your server can serve clients

for longer than they will exist in many cases.



--

All the best,



Berend de Boer





           ------------------------------------------------------

           Awesome Drupal hosting: https://www.xplainhosting.com/

On Jul 28, 2011, at 3:23 AM, Berend de Boer wrote:



> There are levels of REST, so I suggest you don't worry too much about

> HATEOAS.



This is serious mis-information, Berend.



The intention behind using the REST architectural style is to create systems

that have a well determined set of properties (certain performance, certain

scalability, certain evolvability ...[1]). These properties are *only* induced

if *all* of RESTs constraints are applied. There is no 'I'll do half of the

constraints and get half of the benefits' approach.



There are no levels of REST. It is an either-or thing.



And, in addition to that, the hypermedia constraint is *the* most important one.

It is the hardest to understand (at least for me it was) but the most

enlightening one also. Instead of putting it aside, I suggest you dive right

into it, all the way until you grok it.



Jan





[1] See the dissertation for all of them.

> On Jul 28, 2011, at 3:23 AM, Berend de Boer wrote:

>

>> There are levels of REST, so I suggest you don't worry too much about

>> HATEOAS.

>

> This is serious mis-information, Berend.

>

> The intention behind using the REST architectural style is to create systems

that have a well determined set of properties (certain performance, certain

scalability, certain evolvability ...[1]). These properties are *only* induced

if *all* of RESTs constraints are applied. There is no 'I'll do half of the

constraints and get half of the benefits' approach.

>

> There are no levels of REST. It is an either-or thing.



Jan - let's not do this to REST. It is a constraint-driven development of

software architecture for networked apps. There are many many ways to get

certain quality attributes, and making reasonable tradeoffs is an essential part

of building that architecture.



Subbu

On Jul 28, 2011, at 8:25 PM, Subbu Allamaraju wrote:



> > On Jul 28, 2011, at 3:23 AM, Berend de Boer wrote:

> >

> >> There are levels of REST, so I suggest you don't worry too much about

> >> HATEOAS.

> >

> > This is serious mis-information, Berend.

> >

> > The intention behind using the REST architectural style is to create systems

that have a well determined set of properties (certain performance, certain

scalability, certain evolvability ...[1]). These properties are *only* induced

if *all* of RESTs constraints are applied. There is no 'I'll do half of the

constraints and get half of the benefits' approach.

> >

> > There are no levels of REST. It is an either-or thing.

>

> Jan - let's not do this to REST. It is a constraint-driven development of

software architecture for networked apps. There are many many ways to get

certain quality attributes, and making reasonable tradeoffs is an essential part

of building that architecture.

>



Subbu - I am not saying that not doing REST is a bad thing, but REST is (and

surely you know that) defined as a set of constraints. And it is exactly these

constraints that, as a whole, are REST. Suggesting anything along the lines of

'half-REST' or 'low-REST' or 'levels of REST' just hides the fact that it is

critically important to understand the tradeoffs you make when not applying

certain constraints.



http://www.nordsc.com/ext/classification_of_http_based_apis.html



There is no shortcut to thorough understanding of software architectural styles.





Jan







> Subbu

>

>

On Jul 28, 2011, at 12:05 PM, Jan Algermissen wrote:



> Subbu - I am not saying that not doing REST is a bad thing, but REST is (and

surely you know that) defined as a set of constraints. And it is exactly these

constraints that, as a whole, are REST. Suggesting anything along the lines of

'half-REST' or 'low-REST' or 'levels of REST' just hides the fact that it is

critically important to understand the tradeoffs you make when not applying

certain constraints.

>

> http://www.nordsc.com/ext/classification_of_http_based_apis.html

>

> There is no shortcut to thorough understanding of software architectural

styles.



I don't necessarily buy such a classification for several reasons. It may be

good as a learning aid, but no more. In fact, meeting certain qualities takes a

lot more in practice than simply following the script. That aside, I don't find

the assertion that "is an either-or thing" useful.



Subbu

Subbu Allamaraju wrote:

>

> I don't necessarily buy such a classification for several reasons. It

> may be good as a learning aid, but no more. In fact, meeting certain

> qualities takes a lot more in practice than simply following the

> script. That aside, I don't find the assertion that "is an either-or

> thing" useful.

>



Disagree.  I see REST as the long-term goal of an evolving system, an

ideal against which to measure development.  If REST mismatches are

ignored, what yardstick is the system's development to be measured by?

So I see REST as black-and-white, but with no implied criticism towards

systems which don't measure up.  There are aspects of my own system

which aren't RESTful:  in some cases they're considered bugs, while in

others I simply don't care because being strictly RESTful brings nothing

to the table -- but my understanding of the mismatches is critical to my

knowing the difference and being able to categorize/prioritize.  I don't

see what is to be gained by pretending those mismatches don't exist.



-Eric

On Jul 28, 2011, at 12:45 PM, Eric J. Bowman wrote:



> Disagree.



Fair enough.



>  I see REST as the long-term goal of an evolving system, an

> ideal against which to measure development.  If REST mismatches are

> ignored, what yardstick is the system's development to be measured by?

> So I see REST as black-and-white, but with no implied criticism towards

> systems which don't measure up.  There are aspects of my own system

> which aren't RESTful:  in some cases they're considered bugs, while in

> others I simply don't care because being strictly RESTful brings nothing

> to the table -- but my understanding of the mismatches is critical to my

> knowing the difference and being able to categorize/prioritize.  I don't

> see what is to be gained by pretending those mismatches don't exist.



There is no pretension. There are folks who are blindly looking at these

classifications trying to comply without understanding why they should or should

not care. Then there are hecklers picking the same classifications and asking to

show something RESTful in real world. This is the reality today, and

uncompromising guidance is not what is needed.



Subbu

Subbu Allamaraju wrote:

>

> Eric J. Bowman wrote:

>

> > Disagree.

>

> Fair enough.

>

> >  I see REST as the long-term goal of an evolving system, an

> > ideal against which to measure development.  If REST mismatches are

> > ignored, what yardstick is the system's development to be measured

> > by? So I see REST as black-and-white, but with no implied criticism

> > towards systems which don't measure up.  There are aspects of my

> > own system which aren't RESTful:  in some cases they're considered

> > bugs, while in others I simply don't care because being strictly

> > RESTful brings nothing to the table -- but my understanding of the

> > mismatches is critical to my knowing the difference and being able

> > to categorize/prioritize.  I don't see what is to be gained by

> > pretending those mismatches don't exist.

>

> There is no pretension. There are folks who are blindly looking at

> these classifications trying to comply without understanding why they

> should or should not care. Then there are hecklers picking the same

> classifications and asking to show something RESTful in real world.

> This is the reality today, and uncompromising guidance is not what is

> needed.

>



REST's uniform interface constraints aren't meant as classification

tools.  My take on REST comes more from Chapter 6, e.g. "REST...

capture[s] all of those aspects of a distributed hypermedia system that

are considered central to the behavioral and performance requirements

of the Web, such that optimizing behavior within the model will result

in optimum behavior within the deployed Web architecture."



The hypertext constraint isn't more or less important than, say, self-

descriptive messaging; those four constraints taken *together* are what

distinguishes a network-based API from a library-based API (6.5.1).

This is the paradigm shift HTTP unwittingly stumbled upon (which Roy's

thesis is about):  that instead of distributing objects, generic object

interfaces may be distributed with tremendous benefits (Chapter 2.3).

Roy puts it best in 6.5.2:



"

What makes HTTP significantly different from RPC is that the requests

are directed to resources using a generic interface with standard

semantics that can be interpreted by intermediaries almost as well as

by the machines that originate services. The result is an application

that allows for layers of transformation and indirection that are

independent of the information origin, which is very useful for an

Internet-scale, multi-organization, anarchically scalable information

system. RPC mechanisms, in contrast, are defined in terms of language

APIs, not network-based applications.

"



Roy's elaboration on that statement, are the four uniform (generic)

interface constraints.  How is that possible without hypertext driving

application state?  If you leave that out, you don't have a network-

based application.  The same can be said for all the uniform interface

constraints; without them other constraints, like caching, cannot bring

about the desired properties in Chapter 2.  Grasping them as a set

leads to the inevitable "I have seen the light" moment (which inspired

Roy to write 'em down), and charges of shamanism, pedantry or of being

uncompromising.



Which is my long-standing criticism of REST -- this makes it hard to

teach to the point it diminishes the value of REST.  But I contend that

it's no more valuable to water REST down to include library-based APIs,

which as far as I know (as nobody has convincingly falsified Roy's

thesis) are all that's possible without any of the uniform interface

constraints, even if the results are cacheable.  It isn't just missing

a constraint, it's missing the point.



-Eric

On Jul 28, 2011, at 4:16 PM, Eric J. Bowman wrote:



> REST's uniform interface constraints aren't meant as classification

> tools.



That was in reference to a link that Jan posted in this thread that I was

responding to.



Subbu

Subbu Allamaraju wrote:

>

> > REST's uniform interface constraints aren't meant as classification

> > tools.

>

> That was in reference to a link that Jan posted in this thread that I

> was responding to.

>



Right, that's also what I was responding to, I was being politic by not

re-mentioning my criticism of that link though... oops.  :-)



-Eric

On Jul 27, 2011, at 5:35 PM, Daniel Roussel wrote:



> Hi,

>

> I've been reading a lot about how to do "proper" REST this week and the more I

read, the more I'm lost, especially the HATEOAS part I fear.



Don't worry - it was the same for me. It takes your whole mind to shift. Mostly,

dumping off OO-brain damage :-)



>

> First, to give some context, the company I work for develops mobile

applications for clients. Most of the time, they want to get an iPhone native

application, an Android application and a traditional Web based Application to

cover the other mobile phones out there.

>

> The way we are currently doing things is the good old (bad?) RPC over HTTP

way. We define a bunch of URI which are coded inside the different apps, we

exchange data as JSON, etc.  This week, trying to do things in a better way,

I've begin a more serious study of REST and how to do it properly.

>

> What I really can't wrap my head around is how, technically, have HATEOAS in a

native application? I mean, when building a native application, I have tables to

display lists, buttons to do some things, etc. My understanding is that all

those should be displayed based on the data (hypermedia) received from the

server. Is that right?



Yes, just like a browser works.





>

> A concrete example would be a hotel room rental service. The person would open

the application and have fields to enter the from/to dates. It would then tap a

"Get Available Rooms". The app would call the server and get back a list of

rooms along with prices and other details. From there the person could select

one room and rent it.

>

> The RPC way of coding this is obvious to me but I have no idea how I'd do that

in a proper REST way!



Well, if the end user is a human - use HTML.



> What bugs me is that every way I look at it, the client application would

still be tightly coupled to the service. I understand how I would only need to

GET the http://rent-a-room.com URI hardcoded and then in the response I would

have the http://rent-a-room.com/available-rooms URI given. But... My application

would expect each "call" to return some pre-defined data and "rel", those can't

appear out of the blue?!



Right - your client side code should only *react* on stuff it finds, not

*expect* it. If there is a human user directly involved, let the human do the

'expecting' (much like you expect certain stuff from Amazon.com even if your

browser does not).



If the client side code needs to do more stuff without user involvement than a

browser (e.g. browser fetches stylesheets, JS, images) you need to roll you own

media type and build your app based on the hypermedia controls you define in

that media type.



>

> I guess what I'm trying to say is that both the business process and the data

exchanged must be known to my client application at the moment of coding it, and

those can't change without breaking existing clients. But reading about REST,

every is talking about loose coupling and not breaking clients... I just don't

see it.

>

> What am I missing?

>



Nothing, really. You are spot on. The thing is that in networked systems the

client can never be sure that the server does not change. Instead, the client

must be coded to take the least for granted and make the most out of HTTP's

error responses to fail most gracefully.



REST does not make the problem go away that is hidden by RPC-style approaches.

REST simply makes the fact explicit that control over uncontrollable peers is an

illusion. - and comes with a bunch of suggestions how to suffer the least from

the effects of evolving peers.



Most of all REST changes the way you think about networked applications in the

first place.



Jan





> Thanks a lot and sorry if it is a stupid question!

>

>

Sometimes, we can go on and develop a client solution using web apps, but

sometime there is no way out and we need to do a native application.



I read some parts of Mr. Fielding thesis again and many of his comments on his

blog and I think what wasn't clear (still not totally I fear) to me was what

knowledge should be exposed "a priori" and what should be learned "a

posteriori".  My initial understanding was that "almost" nothing was to be known

a priori and that did not make any sense because without some semantic knowledge

of the received media, a client application can do nothing useful.  What good is

it to get a bunch of URI if I have no idea what they are!



Now, my understanding of it is that what MUST be known a priori are the Media

Types which will be exchanged along with the possible relationship.  A

particular client would obviously be coded to support this/those media types. 

Just as a browser understands a resource of type text/html, image/jpeg, etc, my

app would understand resources of type application/rent-a-room+xml for example.



This is the semantic knowledge needed to perform useful work.  This is how a

client knows what relation types to look for to navigate.  This is how it can

know what to present to the screen and how.  So in essence, I believe that my

theoretical "Room Rental" application could be compared to a web browser which

handles "Rent-a-Rooms" documents instead of HTML documents.  And what this

means, is that this "Rent-a-Room" browser could navigate any server that is

serving resources of the type "application/rent-a-room+xml" and on the flip

side, a server could provide room rental services to anyone who understand this

content type without anyone knowing any implementation details.



Am I far off or am I starting to get it a bit more?



--- In rest-discuss@yahoogroups.com, Jan Algermissen <algermissen1971@...>

wrote:

>

>

> On Jul 27, 2011, at 5:35 PM, Daniel Roussel wrote:

>

> > Hi,

> >

> > I've been reading a lot about how to do "proper" REST this week and the more

I read, the more I'm lost, especially the HATEOAS part I fear.

>

> Don't worry - it was the same for me. It takes your whole mind to shift.

Mostly, dumping off OO-brain damage :-)

>

> >

> > First, to give some context, the company I work for develops mobile

applications for clients. Most of the time, they want to get an iPhone native

application, an Android application and a traditional Web based Application to

cover the other mobile phones out there.

> >

> > The way we are currently doing things is the good old (bad?) RPC over HTTP

way. We define a bunch of URI which are coded inside the different apps, we

exchange data as JSON, etc.  This week, trying to do things in a better way,

I've begin a more serious study of REST and how to do it properly.

> >

> > What I really can't wrap my head around is how, technically, have HATEOAS in

a native application? I mean, when building a native application, I have tables

to display lists, buttons to do some things, etc. My understanding is that all

those should be displayed based on the data (hypermedia) received from the

server. Is that right?

>

> Yes, just like a browser works.

>

>

> >

> > A concrete example would be a hotel room rental service. The person would

open the application and have fields to enter the from/to dates. It would then

tap a "Get Available Rooms". The app would call the server and get back a list

of rooms along with prices and other details. From there the person could select

one room and rent it.

> >

> > The RPC way of coding this is obvious to me but I have no idea how I'd do

that in a proper REST way!

>

> Well, if the end user is a human - use HTML.

>

> > What bugs me is that every way I look at it, the client application would

still be tightly coupled to the service. I understand how I would only need to

GET the http://rent-a-room.com URI hardcoded and then in the response I would

have the http://rent-a-room.com/available-rooms URI given. But... My application

would expect each "call" to return some pre-defined data and "rel", those can't

appear out of the blue?!

>

> Right - your client side code should only *react* on stuff it finds, not

*expect* it. If there is a human user directly involved, let the human do the

'expecting' (much like you expect certain stuff from Amazon.com even if your

browser does not).

>

> If the client side code needs to do more stuff without user involvement than a

browser (e.g. browser fetches stylesheets, JS, images) you need to roll you own

media type and build your app based on the hypermedia controls you define in

that media type.

>

> >

> > I guess what I'm trying to say is that both the business process and the

data exchanged must be known to my client application at the moment of coding

it, and those can't change without breaking existing clients. But reading about

REST, every is talking about loose coupling and not breaking clients... I just

don't see it.

> >

> > What am I missing?

> >

>

> Nothing, really. You are spot on. The thing is that in networked systems the

client can never be sure that the server does not change. Instead, the client

must be coded to take the least for granted and make the most out of HTTP's

error responses to fail most gracefully.

>

> REST does not make the problem go away that is hidden by RPC-style approaches.

REST simply makes the fact explicit that control over uncontrollable peers is an

illusion. - and comes with a bunch of suggestions how to suffer the least from

the effects of evolving peers.

>

> Most of all REST changes the way you think about networked applications in the

first place.

>

> Jan

>

>

> > Thanks a lot and sorry if it is a stupid question!

> >

> >

>





--- In rest-discuss@yahoogroups.com, "Daniel Roussel" <daniel@...> wrote:

>

> Hi,

>

> I've been reading a lot about how to do "proper" REST this week and the more I

read, the more I'm lost, especially the HATEOAS part I fear.

>

>

> First, to give some context, the company I work for develops mobile

applications for clients.  Most of the time, they want to get an iPhone native

application, an Android application and a traditional Web based Application to

cover the other mobile phones out there.

>

> The way we are currently doing things is the good old (bad?) RPC over HTTP

way.  We define a bunch of URI which are coded inside the different apps, we

exchange data as JSON, etc.  This week, trying to do things in a better way,

I've begin a more serious study of REST and how to do it properly.

>

> What I really can't wrap my head around is how, technically, have HATEOAS in a

native application?  I mean, when building a native application, I have tables

to display lists, buttons to do some things, etc.  My understanding is that all

those should be displayed based on the data (hypermedia) received from the

server.  Is that right?

>

> A concrete example would be a hotel room rental service.  The person would

open the application and have fields to enter the from/to dates.  It would then

tap a "Get Available Rooms".  The app would call the server and get back a list

of rooms along with prices and other details.  From there the person could

select one room and rent it.

>

> The RPC way of coding this is obvious to me but I have no idea how I'd do that

in a proper REST way!  What bugs me is that every way I look at it, the client

application would still be tightly coupled to the service.  I understand how I

would only need to GET the http://rent-a-room.com URI hardcoded and then in the

response I would have the http://rent-a-room.com/available-rooms URI given.

But...  My application would expect each "call" to return some pre-defined data

and "rel", those can't appear out of the blue?!

>

> I guess what I'm trying to say is that both the business process and the data

exchanged must be known to my client application at the moment of coding it, and

those can't change without breaking existing clients.  But reading about REST,

every is talking about loose coupling and not breaking clients... I just don't

see it.

>

> What am I missing?

>

> Thanks a lot and sorry if it is a stupid question!

>

"Daniel Roussel" wrote:

>

> Now, my understanding of it is that what MUST be known a priori are

> the Media Types which will be exchanged along with the possible

> relationship.  A particular client would obviously be coded to

> support this/those media types.  Just as a browser understands a

> resource of type text/html, image/jpeg, etc, my app would understand

> resources of type application/rent-a-room+xml for example.

>



My usual caveats still apply -- this isn't quite REST, because

intermediaries won't understand the media type (which should be

registered as application/vnd.rent-a-room+xml as your syntax is reserved

for registered, standards-track media types; or, use application/x.rent-

a-room+xml if you don't intend to register your media type).  On

the Web, the desired property of scalability is achieved by re-using

ubiquitous media types. There is nothing about renting a room which

can't be expressed as HTML, so why not re-use HTML?  That way, all the

vast-and-sundry components which do interesting things with ubiquitous

media types like text/html can participate in the communication.



When you send unknowns in Content-Type, you limit yourself to caching,

and maybe not even that as many caches are configured to only cache a

handful of ubiquitous media types which cover the bulk of the traffic

they encounter.  Why waste cache resources on media types nobody uses?

What do links look like in application/vnd.rent-a-room+xml, and how are

intermediaries supposed to recognize them as links?



Various other desired properties of REST are impacted as well, like

maintainability -- better to re-use standard libraries most developers

understand, than custom libraries code maintainers have to be trained

on.  Most HTTP components out there have a-priori knowledge of <a> in

multiple media types, which is why they can follow links.  REST is

about playing to the capabilities of the deployed Web infrastructure,

rather than bucking them.



-Eric

Are there any intermediaries that really care about specific media types?



If so, it must be the devil's own work trying to keep them up to date as the set

of standard media types grows, after those intermediaries have been deployed.



Jim

Mike Kelly wrote:

>

> The only significant intermediary processable content is html +

> ESI... which doesn't even have a media type identifier.

>



Ummm, images?  Many ISP-targeted Web accelerator products will muck

about with ubiquitous image types, i.e. will compare the displayed size

with the raw size (which they can do via their a-priori knowledge of

HTML and CSS media types), and shrink images accordingly.  Stylesheets

are also highly cacheable, text/css is cached by everything which caches

text/html.



-Eric

Note for example that any user of tethering of an iPhone with o2 in the UK will

get through a translating intermediary that rewrites all html pages all the

time, aggregating all content in one file (aka includes all the javascript and

css right inside the page, trying to compensate the fact that 3g networks can

have great bandwidth but crap latency).



Of course those same translators also completely ruin xhtml+xml, as they don't

bother translating to a correct version. But that's beyond the point.



Seb

________________________________________

From: rest-discuss@yahoogroups.com [rest-discuss@yahoogroups.com] on behalf of

Eric J. Bowman [eric@...]

Sent: 28 July 2011 20:29

To: Mike Kelly

Cc: rest-discuss@yahoogroups.com

Subject: Re: [rest-discuss] REST and HATEOAS in the context of native

applications?



Mike Kelly wrote:

>

> The only significant intermediary processable content is html +

> ESI... which doesn't even have a media type identifier.

>



Ummm, images?  Many ISP-targeted Web accelerator products will muck

about with ubiquitous image types, i.e. will compare the displayed size

with the raw size (which they can do via their a-priori knowledge of

HTML and CSS media types), and shrink images accordingly.  Stylesheets

are also highly cacheable, text/css is cached by everything which caches

text/html.



-Eric





------------------------------------



Yahoo! Groups Links

Jim Webber wrote:

>

> Are there any intermediaries that really care about specific media

> types?

>



I take the view that there's no way to know; therefore, I make it as

easy as possible for such intermediaries to evolve by not precluding

their use.  Did anyone anticipate Google Desktop Accelerator, which

does DNS lookahead on various media types?  No, but everyone benefits

who uses ubiquitous types whose linking semantics are well-known.

Also, antivirus gateways may filter on media types, i.e. images.



>

> If so, it must be the devil's own work trying to keep them up to date

> as the set of standard media types grows, after those intermediaries

> have been deployed.

>



That's just it.  Many caches out there only care about a relative

handful of media types which have been around forever.  Media type

proliferation is a problem; whereas the orderly evolution of new,

standardized types is not, because it gives intermediary vendors a

fighting chance to keep up.



-Eric

Mike Kelly wrote:

>

> Because it's a media type that provides a graphical user interface for

> humans. It carries a lot of unnecessary baggage and under-delivers as

> a machine interface.

>



XForms is easily machine-driven, provided the machine user can be made

to understand the markup, which is possible via annotation with RDFa or

microdata; HTML forms have been manipulated by machines since forever.



>

> I registered a couple of generic media types (hal+xml & hal+json)

> intended to serve as 'html for machines', and I'm hoping people will

> adopt it and also contribute to it's continuing development.

>



I didn't realize those were standards-track, thought they were vnd.?

Regardless, the more they're adopted, the more RESTful they become;

uptake provides the incentive for intermediary developers to target

them with unique behaviors to increase their scalability.



-Eric

Mike Kelly wrote:

>

> Right, that is a lot of baggage just to cover the basic hypertext

> requirements of most machine applications. Generally, people want to

> make adoption of their service as painless as possible for their

> consumers.

>



While overlooking the fact that REST considers intermediaries to be

consumers, too, not just user-agents.  I agree, more work needs to be

done on machine-user-targeted media types, but at the present time

these are not ubiquitous enough to gain the full benefits of REST.



Again, everything comes down to trade-offs; more baggage is A-OK if it

leads to greater scalability, whereas if that benefit of REST isn't as

important to those using the system, then non-ubiquitous media types

may be OK.  I see REST as a tool to understand such trade-offs in

system design.



-Eric

Daniel Roussel wrote:

>

> This is badly worded, a mime-type identifies the payload type, but the

> payload type must still be an hypermedia one.  HTML is an hypermedia,

> XML by itself is not, but one can define a specific hypermedia type

> based on XML or JSON, or even embedded in a new image format.

>



Pretty much anything can be a hypertext type, consider a .wav served

with Link headers.  XML is also hypertext, provided the linking is

XInclude or XPointer, or XML PIs.  Generally, though, raw XML semantics

are insufficient for driving application state, which is why

application/xml is avoided in REST.



-Eric

Daniel Roussel wrote:

>

> No offense, sincerely, but I disagree.  HTML is a content-type meant

> to be rendered by a web browser and its semantics are of (almost) no

> use for any application other then a web browser.

>



I've found the semantics of HTML quite useful in a variety of contexts;

for example, <ul> and <ol> are universally understood methods of

presenting lists of 'stuff' with specific semantics (whether or not

their order is important); <table> is quite useful for serializing

arrays.  So I can model many custom data types using HTML media types,

and have it understood perfectly well by non-browser consumers using

standard libraries commonly found all over the Web.



>

> Parsing web pages to drive a native iPhone or Android app is not a

> sensible choice at all.

>



OTOH, what I see as not sensible, is for these native apps to re-invent

various wheels like buttons, which could just as easily have been

implemented using standard markup.  As I am unfamiliar with such apps,

I don't know whether they're REST or anti-REST, though.



>

> And the choice of html, json or xml is only an issue of resource

> representation.

>



Not really.  I know how to make hyperlinks universally understood in

HTML media types, as every component out there groks the semantics of

<a> and <link/>, but I don't know of any universally understood linking

semantics for JSON; XML supports XInclude and XLink but not <a> or

<link/>, so I choose a media type with semantics which match my needs.



>

> A resource can have many different representation, that for sure is

> permitted.  There is nothing about renting a room which can't be

> expressed in english, but I would not send a wav file either.

>



For exactly the same reasons that sending it as JSON makes no sense --

lack of semantics in the representation.  REST's hypertext constraint

is all about those semantics -- .wav files have no hypertext semantics,

which is why they're a poor choice for driving application state.  I'm

not saying JSON has no place in REST, only that at the present time,

it's a poor choice for driving application state.



>

> Even more, using mime-type is necessary because we are using HTTP as

> our protocol, I'm sure we could create a brand new protocol and a

> different way of defining messages and it could still be RESTful.

>



Actually, the use of Internet Media Types is required by REST regardless

of protocol; this doesn't mean the syntax of the identifier has to be

the same as it appears in the IANA registry, but HTML should still be

HTML regardless of what protocol it's served with.



>

> As for cacheability, the constraint is that resource must be

> cacheable by the client.

>



REST requires the cacheability of representations to be explicitly

stated, says nothing about client-cacheable=REST.  The difference is

between having a library-based API (where intermediaries cannot

participate in the communication) and a network-based API (where

intermediaries can and do participate), with the latter being the whole

point of REST as a style; if no intermediaries grok the representation

and most won't cache it since the media type is unknown, the essence of

REST is missing.



>

> The way I interpret this, is that my application should be able to

> cache a room representation if marked as being cacheable.  REST is an

> architectural style, it does not mandate the use of any protocol or

> data type, merely how to model a system.

>



As a network-based API, meaning intermediaries must also be able to

participate, which they can't do if they're unfamiliar with the

semantics of the representation.  Shoe-horning things into HTML, Atom

etc. brings about benefits which offset the awkwardness of such

implementations, such benefits do not accrue when using library-based

APIs.



-Eric