REST is self-describing

[Benjamin van der Veen]

I hear this line about how a proper REST system does not require a consumer to have any a priori knowledge of the system to consume it. How is this possible without a standardized method of describing services (in the spirit of WSDL)? Why is this a design goal for a system anyway? I work on mobile, and if I'm going to invest effort in writing a client for a service, you can bet I'm going to have a ton of a priori knowledge about it.

[Kevin Swiber]

On Thu, Sep 1, 2011 at 10:30 PM, Benjamin van der Veen <b...@bvanderveen.com> wrote:

I hear this line about how a proper REST system does not require a consumer to have any a priori knowledge of the system to consume it. How is this possible without a standardized method of describing services (in the spirit of WSDL)? Why is this a design goal for a system anyway? I work on mobile, and if I'm going to invest effort in writing a client for a service, you can bet I'm going to have a ton of a priori knowledge about it.

This one stumps me, too.

Anyone who's ever tried to build "the ad-hoc reporting engine that dynamically builds UI elements based on configured input types" knows this is just a bad idea..

Without prior knowledge, your client views will contain minimal UI interaction and generally look ridiculous.

I've seen this concept described 2 ways as it pertains to REST.

1. Include links in your hypermedia to structural schema and validation information. (type=string, maxlength=14, position=1)

2. Include links in your hypermedia that describe taxonomy.  (See http://blog.kevburnsjr.com/self-descriptive-hypermedia-in-riak)

Method #1 is the same bad idea mentioned earlier.

Method #2 only really makes sense if your consumers require that level of detail about the resource.

I'd love to hear some insight into this.  Right now, I'm not sold this makes sense.

So, the short version:  Me, too!

--
Kevin Swiber

Projects: https://github.com/kevinswiber
Twitter: @kevinswiber

[Jason Sirota]

There's some confusion about what a priori knowledge of a rest system
actually entails. Darrel or Sebastien can explain it better but it
divides up into two categories:

1. Hypermedia - you have no a priori knowledge of the uri structure
because each resource you request contains links to state transitions
that are identified by name. Such as an order has a "cancel" state.
That cancel state may or may not be available based on other business
rules on the order (such as orders can't be canceled after they are
shipped).

Providing state transitions via hypermedia allows the server to change
uri schemes without updating clients. As long as the client checks for
the existence of the cancel state and then calls the link specified in
the href, the server and the client can evolve independently. This is
especially important for a service provider for mobile where you don't
have control over your customers mobile apps.

2. Media Types - the misconception about documentation is that NO
documents are allowed. This is definitely not true. In fact, documents
for media types are encouraged. Media types are equivalent to "HTML"
they say what a resource document may contain but not whether it will
contain it or what data is in it. For example in the order scenario
above, the document for the order media type would say that a cancel
state transition is possible but not guaranteed to be there.

Its fair to say also that without hypermedia, you cannot have a rest
api without uri documentation, its just not possible.

Jason

--
Jason Sirota
ja...@sirotamail.com
http://twitter.com/jasonsirota
http://jasonsirota.com/

[Jason Sirota]

Providing state transitions via hypermedia allows the server to change
uri schemes without updating clients. 

Let me correct one thing here, the server can change uri schemes and state transitions as business rules evolves. Thus if your business decides that it wants to allow cancellations after items are shipped it can do so without informing clients of a documentation change.

The alternative is to have a GET order/1/cancel uri or if you're using http verbs a DELETE /order/1 action and the server returns an error if cancellation is not allowed. An acceptable alternative but could be jarring if your clients are both not expecting state changes (because you didn't tell them about it ahead of time) and did not handle the error. With hypermedia, the client application is designed to not expect cancel to be there and therefore can account for situations where cancel is allowed and not allowed.

Jason

[Kevin Swiber]

Ah, so perhaps "a priori knowledge" really only refers to URI structure.  I'm totally cool with URI links to child resources and state transitions.  Thanks for that clarification, Jason.

For me, if I'm taking the HATEOAS path, I'd like to define "self-descriptive hypermedia" as a document that:

- Has a known Content-Type (i.e., vnd.super-app.welcome-mat)

- Provides links to state transitions

- Provides links to child resources

Thoughts?

If I were to use a JavaScript framework that helps support REST clients on the Web, I think I would look to see that it implements that opinion. (Thread cross-over.)

[Benjamin van der Veen]

On Thu, Sep 1, 2011 at 11:46 PM, Jason Sirota <ja...@sirotamail.com> wrote:

Providing state transitions via hypermedia allows the server to change
uri schemes without updating clients. 

Let me correct one thing here, the server can change uri schemes and state transitions as business rules evolves. Thus if your business decides that it wants to allow cancellations after items are shipped it can do so without informing clients of a documentation change.

This seems a little pie-in-the-sky if you ask me. If I was building an iPhone app that implemented a front-end for this example service, I bet that there are non-trivial UI changes that would need to be made if the business rules changed as you described here. So again, I'm questioning why this sort of thing is a design goal. 

This also leads to my next question…

 

On Fri, Sep 2, 2011 at 8:36 AM, Kevin Swiber <ksw...@gmail.com> wrote:

The alternative is to have a GET order/1/cancel uri or if you're using http verbs a DELETE /order/1 action and the server returns an error if cancellation is not allowed. An acceptable alternative but could be jarring if your clients are both not expecting state changes (because you didn't tell them about it ahead of time) and did not handle the error. With hypermedia, the client application is designed to not expect cancel to be there and therefore can account for situations where cancel is allowed and not allowed.

Ah, so perhaps "a priori knowledge" really only refers to URI structure.  I'm totally cool with URI links to child resources and state transitions.  

What are state transitions? Does that refer to resources like /orders/1/cancel? Why would you do that rather than DELETE /orders/1?

[Chris Roland]

I really like method #2 (taxonomy).

I think we work with 2-3 degrees of information when we make
decisions. Having a clear taxonomy will definitely help if single
page web apps become more popular.

For example, if I'm on a client running a single page web app and I
want to remove a contact from a customer order. There is a clear path
to the contact data and remove resource, without stuffing it all into
one document.



Chris Roland
Twitter: @ChrisRoland
Email: cbro...@gmail.com

On Sep 1, 10:51 pm, Kevin Swiber <kswi...@gmail.com> wrote:
> On Thu, Sep 1, 2011 at 10:30 PM, Benjamin van der Veen <b...@bvanderveen.com>wrote:
>
> > I hear this line about how a proper REST system does not require a consumer
> > to have any a priori knowledge of the system to consume it. How is this
> > possible without a standardized method of describing services (in the spirit
> > of WSDL)? Why is this a design goal for a system anyway? I work on mobile,
> > and if I'm going to invest effort in writing a client for a service, you can
> > bet I'm going to have a ton of a priori knowledge about it.
>
> This one stumps me, too.
>
> Anyone who's ever tried to build "the ad-hoc reporting engine that
> dynamically builds UI elements based on configured input types" knows this
> is just a bad idea..
>
> Without prior knowledge, your client views will contain minimal UI
> interaction and generally look ridiculous.
>
> I've seen this concept described 2 ways as it pertains to REST.
>
> 1. Include links in your hypermedia to structural schema and validation
> information. (type=string, maxlength=14, position=1)

> 2. Include links in your hypermedia that describe taxonomy.  (Seehttp://blog.kevburnsjr.com/self-descriptive-hypermedia-in-riak)

[Jason Sirota]

This seems a little pie-in-the-sky if you ask me. If I was building an iPhone app that implemented a front-end for this example service, I bet that there are non-trivial UI changes that would need to be made if the business rules changed as you described here. So again, I'm questioning why this sort of thing is a design goal. 

Pie-in-the-sky indeed. That's also one of my main challenges with this architecture pattern as well. I outlined my feelings in another group and I need to transfer those to my blog at some point.  Here was the summary of my point about changing functionality over time:

Category 2: Constraining functionality over time (Removing the cancel function) 

...This one includes saying at one point in time a particular function is available but later you want to remove that functionality. If the client obeys hypermedia, then that @rel will no longer be available. I still believe this will break client functionality, in most clients executing a "rel" means something, so a client has to be very clever to adjust functionality (remove the cancel button) based on whether a @rel is available or not. This requires just as much diligence in obeying hypermedia constrants on the consumer as well as the producer of a service. Therefore, the level-of-effort shift is negated.

My point here is that there is a balance between architectural integrity and level-of-effort (yes, I realize I am thinking as a dev manager, can't fault a bird for flying), specifically as it relates to time-to-market. So lets say you do develop a fully hypermedia-driven server API for your clients to use. Chances are that requires quite a bit more development effort than a simple CRUD-based API that exposes objects. The theory goes that by shifting your development effort to the server level, you allow your clients to save effort by not forcing them to make updates to their app as the server evolves. In practice, however, this just means the clients has to expend extra effort up front to make sure the client application adheres to the same hyper media goals. This is necessary so that when you remove functionality like the cancel button, those non-trivial UI changes are handled up front.

So say that's a goal you agree with, now you've just killed your TTM advantage because you need to put extra effort up front both on the server and the client. 

OK, that occurs if your company controls both the server and the client. But we already established that REST works better if your company does not control both since it allows your server to evolve independently without breaking (most) clients. But wait! If your company is the kind that has a server API but relies on customers to build the clients, then you certainly don't want to hinder them from developing their client applications quickly. So the end result is that you provide URI-space and state transition documentation as well as hypermedia. You don't guarantee that your clients use hypermedia and you just negated the up-front time you put into developing a hypermedia API.

Back to the idea that its beneficial where you can fully control your client and your server. You can make 100% sure that all the clients on your server are fully hypermedia-compliant. You've put all that extra effort into making both your server and your client evolve independently even in non-trivial scenarios. And you don't care about TTM, you're willing to put in the effort. At best there are some long-tail benefits that you can reap.

All this to say that while the architectural theory of hypermedia may be sound (especially as it relates to the web), the business case for doing so as an abstract data API seems shaky except in a few circumstances. And specifically, the business case seems weakest where its supposed to have the most gain. This is why I believe the hypermedia portion of REST has not gained traction the way the HTTP semantics generally have. 

This also leads to my next question…

 

On Fri, Sep 2, 2011 at 8:36 AM, Kevin Swiber <ksw...@gmail.com> wrote:

The alternative is to have a GET order/1/cancel uri or if you're using http verbs a DELETE /order/1 action and the server returns an error if cancellation is not allowed. An acceptable alternative but could be jarring if your clients are both not expecting state changes (because you didn't tell them about it ahead of time) and did not handle the error. With hypermedia, the client application is designed to not expect cancel to be there and therefore can account for situations where cancel is allowed and not allowed.

Ah, so perhaps "a priori knowledge" really only refers to URI structure.  I'm totally cool with URI links to child resources and state transitions.  

What are state transitions? Does that refer to resources like /orders/1/cancel? Why would you do that rather than DELETE /orders/1?

I was using state transitions to refer to any action that changes the state of a persistent data piece. Canceling an order would be a state transition. So would changing a Customer name or updating a whole customer.

In hypermedia-theory, there is no difference between:

    GET /orders/1/cancel

    DELETE /orders/1

They are the same thing, execute a state transition: "As a user of the orders API, I want to cancel order 1") just a different semantics for doing the same thing.

HTTP Web API theory says those are two different things:

    GET /orders/1/cancel  = As a user of the orders API, I want to execute the "Cancel" remote procedure call (action) on order 1

    DELETE /orders/1 = As a user of the orders API, I want to transition the order 1 state to the state mapped to the DELETE verb

Not a great example but imagine if your RPC call was "CancelOrderAndChangeUPSValueToCanceledAndEmailCustomer(orderid: 1) then it gets hairy

Jason

[Kevin Swiber]

On Fri, Sep 2, 2011 at 1:42 PM, Benjamin van der Veen <b...@bvanderveen.com> wrote:

On Thu, Sep 1, 2011 at 11:46 PM, Jason Sirota <ja...@sirotamail.com> wrote:

Providing state transitions via hypermedia allows the server to change
uri schemes without updating clients. 

Let me correct one thing here, the server can change uri schemes and state transitions as business rules evolves. Thus if your business decides that it wants to allow cancellations after items are shipped it can do so without informing clients of a documentation change.

This seems a little pie-in-the-sky if you ask me. If I was building an iPhone app that implemented a front-end for this example service, I bet that there are non-trivial UI changes that would need to be made if the business rules changed as you described here. So again, I'm questioning why this sort of thing is a design goal. 

This is where theory has a street fight with reality.

As a client, you need to decide your level of compromise, and you certainly need to know up front what the available state transitions are.  Otherwise, you can't effectively support them.

Maybe you hard code all the buttons you need (e.g., "Cancel Order", "Pay").  You can set an enabled/disabled state based on the presence of the links to state transitions (looking for links with the expected rel, [link rel="/link/order/pay"]).

What are state transitions? Does that refer to resources like /orders/1/cancel? Why would you do that rather than DELETE /orders/1?

Well, you wouldn't.  REST doesn't really care about HTTP, but it does care that you use the methods for your chosen protocol in a way that makes sense [1].  Unless you're fetching a representation of the order in a cancelled state, I'd use the DELETE verb.

I think this explains state transitions decently:  http://timelessrepo.com/haters-gonna-hateoas

Disclaimer:  This is all recent opinion for me.  I'm still a REST n00b.

[1] http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post

[Alex Robson]

I am sorry I'm late to this discussion. First off, if you all haven't
discovered these two posts yet, I highly recommend them. Steve Klabnik
says he may write a book on REST, I certainly hope he does.

http://blog.steveklabnik.com/2011/07/03/nobody-understands-rest-or-http.html

and then

http://blog.steveklabnik.com/2011/08/07/some-people-understand-rest-and-http.html

Ok. So, in my opinion, self-description via hypermedia is important if
and only if we can devise a way to create more proactive user agents.
I interpreted Fielding's intent as making it possible for user agents
to carry more burden when interacting with RESTful services. Would
love to hear more about that.

Because I'm a bit of a daydreamer and think more in terms of "wouldn't
it be great if", I would love to do some work on javascript tooling
that's a step closer to Fielding's vision and away from what we have
today. I recently had to interact with a few vendor services over HTTP
which induced a lot of psychic pain. They were complete nonsense and
each came with a 30+ page manual that is constantly being invalidated
as they change their API. REST and reality are street fighting because
REST wants to impose elegance, uniformity and order to service
boundaries while reality is developers slopping APIs together that
make no sense, hurt to use and are just ugly as hell.

I'm still a REST n00b as well but it resonates with how I attempt to
design things. In regards to some things said earlier:

> I work on mobile, and if I'm going to invest effort in writing a client for a service, you can bet I'm going to have a ton of a priori knowledge about it.

Right, but I'd wager that the level of knowledge required to interact
with a system has an inverse relationship with how RESTful the system
is : ) If they're just winging their API instead of trying to adhere
to certain principles, you're going to be reading lots and lots of
documentation and you're at higher risk for a frustrating magnitude of
change if their API changes since their are no standards they've
adhered to. Steve's second blog demonstrates how he uses curl to
discover APIs without having to tunnel through docs.

> What are state transitions? Does that refer to resources like /order/1/cancel? Why would you do that rather than DELETE /orders/1?

Verbs shouldn't go in the URI. Verbs are part of the request, but the
URI should be a path to the resource in question.

In response to whether or not hypermedia's availability is valuable:

As I mentioned before, one goal for REST is the enablement of
intelligent clients. The clients don't exist because there aren't just
tons of RESTful services for us to interact with today. If I had a
javascript/iOS/Silverlight(ugh) library that actively disabled/removed
components of the UI based on what the server makes available in terms
of interactions, I'd use the hell out of that ability.
It's not saving you code or effort today because our tools haven't
matured just yet. I think we've gotten to a point where it's certainly
possible and that's just one great reason this Google group is so
valuable : )

Anyway, that's very rambly, but I only had a few minutes to reply to
this thread and I'm very interested to see if any of this was helpful
or just a lot of non-sense that didn't really resolve any of the
concerns about REST.

Alex

On Sep 2, 3:03 pm, Kevin Swiber <kswi...@gmail.com> wrote:
> On Fri, Sep 2, 2011 at 1:42 PM, Benjamin van der Veen <b...@bvanderveen.com>wrote:
>
>
>
>
>
>
>
>
>
> > On Thu, Sep 1, 2011 at 11:46 PM, Jason Sirota <ja...@sirotamail.com>
> >>  wrote:
>
> >>>  Providing state transitions via hypermedia allows the server to change
> >>>> uri schemes without updating clients.
>

> >>> Let me correct one thing here, the server can change uri schemes *and
> >>> state transitions* as business rules evolves*.* Thus if your business
> >>> decides that it wants to *allow *cancellations after items are shipped

[Kevin Swiber]

On Mon, Sep 5, 2011 at 2:32 PM, Alex Robson <asro...@gmail.com> wrote:

I am sorry I'm late to this discussion. First off, if you all haven't
discovered these two posts yet, I highly recommend them. Steve Klabnik
says he may write a book on REST, I certainly hope he does.

http://blog.steveklabnik.com/2011/07/03/nobody-understands-rest-or-http.html

and then

http://blog.steveklabnik.com/2011/08/07/some-people-understand-rest-and-http.html

Good stuff.  Steve took hours of time I spent researching and consolidated the good parts into a few paragraphs. :)  I will probably use those links next time I hear "REST, what?"

 

As I mentioned before, one goal for REST is the enablement of
intelligent clients. The clients don't exist because there aren't just
tons of RESTful services for us to interact with today. If I had a
javascript/iOS/Silverlight(ugh) library that actively disabled/removed
components of the UI based on what the server makes available in terms
of interactions, I'd use the hell out of that ability.
It's not saving you code or effort today because our tools haven't
matured just yet. I think we've gotten to a point where it's certainly
possible and that's just one great reason this Google group is so
valuable : )

Adding to that and echoing previous statements, I still want my clients responsible for user experience.  Therefore, I need upfront knowledge of the possible use cases.  In JavaScript, I'd likely assign callbacks that enable/disable components based on the existence/absence of known possible links.  I'd be hesitant to dynamically build UI elements based on any link found in the hypermedia response.

Does that deviate from the spirit of REST or is it aligned?

 

[Alex Robson]

I would expect intelligent user agents to be up for interpretation.
Wouldn't it be nice though if you were able to define your user
experience in terms of nouns, verbs and data? To Ben's earlier point;
you do need a certain amount of knowledge about what you're using, but
it would be nice if that were constrained to a nice subset of
information. Not all applications warrant the same level of
sophistication. Some task based or CRUD UIs could probably fall under
the more dynamic user agent behavior.

I think what you're talking about is valid. You can only leverage the
aspects of REST that make sense for your application. I know that the
REST community (including Fielding) are adamant that REST isn't a
spectrum, but I respectfully disagree. I think that most of us have to
work towards REST and that comes in steps rather than making a huge
leap and commitment to something that our tooling may not currently
support.

Alex

On Sep 5, 8:16 pm, Kevin Swiber <kswi...@gmail.com> wrote:

> On Mon, Sep 5, 2011 at 2:32 PM, Alex Robson <asrob...@gmail.com> wrote:
> > I am sorry I'm late to this discussion. First off, if you all haven't
> > discovered these two posts yet, I highly recommend them. Steve Klabnik
> > says he may write a book on REST, I certainly hope he does.
>

> >http://blog.steveklabnik.com/2011/07/03/nobody-understands-rest-or-ht...
>
> > and then
>
> >http://blog.steveklabnik.com/2011/08/07/some-people-understand-rest-a...

[Benjamin van der Veen]

On Sep 5, 2011, at 17:16, Kevin Swiber <ksw...@gmail.com> wrote:

On Mon, Sep 5, 2011 at 2:32 PM, Alex Robson <asro...@gmail.com> wrote:

 

As I mentioned before, one goal for REST is the enablement of
intelligent clients. The clients don't exist because there aren't just
tons of RESTful services for us to interact with today. If I had a
javascript/iOS/Silverlight(ugh) library that actively disabled/removed
components of the UI based on what the server makes available in terms
of interactions, I'd use the hell out of that ability.

You can certainly build clients like that, but you do so with the understanding that "what the server makes available in terms of interactions" is indeed part of the contract between the client and server. I am wary of this idea that if everything just conformed to REST, we could write one client library to rule them all, wash our hands of all client dev forever, and happily hack our API code and deploy totally new functionality without changing the front-end.

Adding to that and echoing previous statements, I still want my clients responsible for user experience.  Therefore, I need upfront knowledge of the possible use cases.  In JavaScript, I'd likely assign callbacks that enable/disable components based on the existence/absence of known possible links.  I'd be hesitant to dynamically build UI elements based on any link found in the hypermedia response.

Agreed. Again, I am not going to code a client that accounts for the possibility that the API might change in semi-arbitrary ways that I can't or won't explicitly define with stakeholders at the outset. As a client developer, I code very defensively against server APIs (if you're not careful, API changes can fully crash an iPhone app), and I am going to need a very clear idea of what the server ought to accept as input or generate as output. If the service is going to change in any significant way (such as adding new state transitions like Jason's customer/order/shipment example) I will likely be re-UX-designing, recoding, and redeploying my client after having a nice discussion with the API devs and business stakeholders. 

On the other hand, if these sorts of variations are a documented part of the API, then I can code a client to that specification. 

Similarly, the service can change in any way as long as it doesn't break my client. ;) If you as a service developer have the balls to roll out changes underneath clients in production—well, it won't be my head on the platter. ;) 

I guess what I'm saying is that, in my view, none of this stuff obviates the need for a versioning system. It just seems to recommend some nice ways to implement common classes of functionality in a way that respects HTTP—like how DELETE /widgets/1 is just kind of more elegant than a SOAP call to DeleteWidgetByID().

[Kevin Swiber]

On Tue, Sep 6, 2011 at 1:40 AM, Benjamin van der Veen <b...@bvanderveen.com> wrote:

I guess what I'm saying is that, in my view, none of this stuff obviates the need for a versioning system. It just seems to recommend some nice ways to implement common classes of functionality in a way that respects HTTP—like how DELETE /widgets/1 is just kind of more elegant than a SOAP call to DeleteWidgetByID().

The good thing is that hypermedia can be versioned.  Some folks do this via the URI (/super-service/v2/door-knob/1), but I'd prefer the MIME type approach (Content-Type: vnd.super-service.door-knob.v2+json).

Bringing some closure on this issue (in my brain)...

To develop smart clients that care about this sort of thing, there are 2 requirements for the REST service.

1. For each version of the API, document state transitions that may appear in the hypermedia response, including whether or not a link is optional.

2. When changing the API in a way that could break clients, release the changes under a new version.

If Roy Fielding would puke on those statements, I'd like to hear a convincing argument for solving the UX problem.  I haven't heard one yet.

For the question, "What about CRUD apps?", all I can say is that I've never in my career written an application that only offers viewing, adding, modifying, or removing rows in a database.  I've only seen CRUD apps in MVC framework demos and Microsoft Access.

[Darrel Miller]

Wow.  There are a whole lot of issues in this thread,  maybe I'll start with the original topic.

I think saying "REST is self-describing" is conflating a couple of things.  First, REST requires that individual messages are "self-descriptive".  Which is really just a fancy way of saying, don't use sessions so that your requests can remain stateless and also, don't allow your client or server to make unstated assumptions about the information that is being passed between them.  i.e. If the client tries to extract information about invoice details from a representation with the media-type application/xml then assumptions are being made and "out-of-band" knowledge is being used, which is not good.

Second, REST resources within an API should be discoverable via links, which is maybe where the "self-describing" term comes from but there certainly is no requirement for a descriptive document like WSDL.  HTTP doesn't require an upfront contract about what "type" will be returned from a request, because it returns metadata in the response which tells you what "media-type" is being returned.  Client application should be built to react to the types that come back, rather than expecting certain types.  Hypermedia documents use link relations to describe conceptually, what a link points to so that the client can identify when it should follow a particular link.

REST, does not say there should be no prior knowledge of a service.  With no coupling at all, the client and server would not be able to do anything useful.  REST asks that you confine the shared knowledge between the client and server in two mechanisms.  Media-types and link relations.  By limiting the coupling to within just these two areas it makes it easier to manage that coupling and makes the independent evolution of the client and the server easier.

Jason is correct in that most of the time when people are talking about not having prior knowledge of a REST service they are talking about  URI structure.  To give a real practical example of how this is possible, take a look at http://amundsen.com/hypermedia/profiles/.  During the hackday at RESTfest we took this document and a number of us built clients and servers based purely on this spec and then were able to successful demonstrate interoperability between clients and servers.  Not only does that spec not define any URIs it, doesn't even define what resources need to exist.  Now, the experiment showed that the spec was slightly underspecified, but only because of missing link relations.

As far as whether REST enables smart or dumb clients, I definitely lean on the side of REST helps you build really dumb clients.  REST clients in my experience work really well when they are just a pretty UI layer over the top of hypermedia based representations.  Think of the web browser, HTML is your REST representation that contains the data and the links and CSS is your thin pretty layer.  All the web browser does is render UI and enable you to follow links.  That to me is the ideal REST client.  The only downside to a web browser is its obsession over HTML.

Without going into too much detail, I have spent the last 5 years building a large business application using a .Net winforms client talking to a REST API.  I use hypermedia extensively to directly control the user experience and I have found it very effective for my scenario.  I come from a fat client background, so I have a ton of past experience using domain objects on the client side and in this kind of application where information naturally wants to live centrally, using thin REST clients against a smart Hypemedia API is, in my opinion, a much better solution.

And if anyone is curious as to what I think is the ideal client library for accessing REST Hypermedia APIs then I have a project here http://restagent.codeplex.com that I am working on.

Regards,

Darrel

[Kevin Swiber]

On Tue, Sep 6, 2011 at 2:27 PM, Darrel Miller <darrel...@gmail.com> wrote:

Wow.  There are a whole lot of issues in this thread,  maybe I'll start with the original topic.

Darrel, thanks for the in-depth response.

 

Jason is correct in that most of the time when people are talking about not having prior knowledge of a REST service they are talking about  URI structure.  To give a real practical example of how this is possible, take a look at http://amundsen.com/hypermedia/profiles/.  During the hackday at RESTfest we took this document and a number of us built clients and servers based purely on this spec and then were able to successful demonstrate interoperability between clients and servers.  Not only does that spec not define any URIs it, doesn't even define what resources need to exist.  Now, the experiment showed that the spec was slightly underspecified, but only because of missing link relations.

That document is exactly what I was looking for. Defining the hypermedia interface using key words such as "MAY," "MUST," and "SHOULD" is key.  When writing a client, I feel I need that information.

Also, your point about not expecting a media-type, but reacting to the response is well-taken. I'm gonna noodle on that a little bit.

Thanks.