A rest api should never have typed resources
214 views
Skip to first unread message
dschulten
Dec 16, 2012, 5:31:13 AM12/16/12
to hyperme...@googlegroups.com
Hi, I could use some help in interpreting Fielding's statement in http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
"A REST API should never have “typed” resources that are significant to the client. Specification authors may use resource types for describing server implementation behind the interface, but those types must be irrelevant and invisible to the client. The only types that are significant to a client are the current representation’s media type and standardized relation names. [ditto]"
Where ditto refers to "[Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC's functional coupling]."
My understanding of this is: a client must not rely on the content of a response in the sense that it must understand previously known attributes of the content in order to be able to use the api.
Example: it should not need to extract a list of coffee choices and their ids and prices from a server response to build a post request which orders two coffees. Or to be more precise, for a rest client it is more or less forbidden to do that. "significant ... are the ... media type and standardized relation names." I read this like so: The media type and associated rels must provide the necessary means to act upon the content, i.e. it must allow the client to post a request for two coffees without understanding the content, but rather just by identifying rel names based on equality and using built-in capabilities of a media type such as an html form's way to instruct the client how to construct a post body.
Do you think I get Fielding's intention correctly?
Especially the role of the media type is not really clear to me. Application specific media types where the client is programmed to look for domain specific stuff defeat the whole idea of avoiding out of band information, that much is clear. But what is it that should be significant about a media type for a client, following Fieldings argument? What are the conditions for a media type suitable for hypermedia?
Dietrich
"A REST API should never have “typed” resources that are significant to the client. Specification authors may use resource types for describing server implementation behind the interface, but those types must be irrelevant and invisible to the client. The only types that are significant to a client are the current representation’s media type and standardized relation names. [ditto]"
Where ditto refers to "[Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC's functional coupling]."
My understanding of this is: a client must not rely on the content of a response in the sense that it must understand previously known attributes of the content in order to be able to use the api.
Example: it should not need to extract a list of coffee choices and their ids and prices from a server response to build a post request which orders two coffees. Or to be more precise, for a rest client it is more or less forbidden to do that. "significant ... are the ... media type and standardized relation names." I read this like so: The media type and associated rels must provide the necessary means to act upon the content, i.e. it must allow the client to post a request for two coffees without understanding the content, but rather just by identifying rel names based on equality and using built-in capabilities of a media type such as an html form's way to instruct the client how to construct a post body.
Do you think I get Fielding's intention correctly?
Especially the role of the media type is not really clear to me. Application specific media types where the client is programmed to look for domain specific stuff defeat the whole idea of avoiding out of band information, that much is clear. But what is it that should be significant about a media type for a client, following Fieldings argument? What are the conditions for a media type suitable for hypermedia?
Dietrich
Mike Amundsen
Dec 16, 2012, 7:13:20 AM12/16/12
to hyperme...@googlegroups.com
I think of it this way.
in an Object-Oriented style, both sender and receiver share an understanding about the possible objects that existing in the domain model. that means they share understanding not just about the "names" of objects, but also the component properties of those objects and the relation between various objects in the problem domain.
in a REST-oriented style, both sender and receiver share an understanding about the possible message formats (media types) used in client-server communications. that means they share understanding not just about the media type names (app/atom+xml, app/svg, app/hal, etc.) but also the way in which the message carries state (data elements) and describes transitions (hypermedia controls).
REST-style systems are designed to share "state", not "objects", therefore the significance of "types" is found in the the media "types". this allows both client and server implementors to use any code style (OO, functional, procedural, etc.) to manipulate state *locally* w/o requiring the other party to share their coding style, object names, etc.
on a few of your points...
"client to post a request for two coffees without understanding the content"
there is no requirement in Fielding's description that clients act w/o understanding _content_. the point is that clients should be able to act w/o sharing knowledge of server-side internal coding details.
"Application specific media types where the client is programmed to look for domain specific stuff defeat the whole idea of avoiding out of band information,"
Fielding is not saying that "app specific media types...defeat" anything. what he is addressing is the "shared understanding" between client and server - which he claims should be limited to the message (media type) itself and not leak into the source code implementation details (e.g. the object model, storage model, etc.) of any server or client.
"What are the conditions for a media type suitable for hypermedia?"
Fielding offered a quote that might help answer that Q:
"Hypermedia is defined by the presence of application control information embedded within, or as a layer above, the presentation of information."[0] most media types lack this "application control information". For example, XML, JSON, CSV have no hypermedia controls. HTML, VoiceXML, Atom, HAL, Siren, Collection+JSON all have hypermedia controls defined as part of a valid message.
I talk about the concept of "hypermedia types" via what I named "H-Factors" in 2010[1]. I expanded on this idea in 2011 and covered one approach to designing hypermedia messages in "Building Hypermedia APIs."[2]. I also recently wrote a blog post that describes mental model for dissecting the messages sent between client and server. It's titled: "Three Levels of Hypermedia Messages"[3] and talks about Structure-, Protocol-, and Application-level semantics.
hopefully, this will give you some ideas.
feel free to continue discussion here or start additional threads, if you like.
Cheers.
mca
--
You received this message because you are subscribed to the Google Groups "Hypermedia Web" group.
To view this discussion on the web visit https://groups.google.com/d/msg/hypermedia-web/-/SFnQcD7rfP0J.
To post to this group, send email to hyperme...@googlegroups.com.
To unsubscribe from this group, send email to hypermedia-we...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/hypermedia-web?hl=en.
Dietrich Schulten
Dec 16, 2012, 7:37:58 AM12/16/12
to hyperme...@googlegroups.com
Thank you very much, especially for pointing out what Fielding is not saying. Just the clarification I needed. Looking forward to look into your suggested reading.
Best regards
Dietrich
Dan Haywood
Dec 16, 2012, 8:09:31 AM12/16/12
to hyperme...@googlegroups.com
On 16 December 2012 12:13, Mike Amundsen <m...@amundsen.com> wrote:
I think of it this way....A really good reply, thx
... I also recently wrote a blog post that describes mental model for dissecting the messages sent between client and server. It's titled: "Three Levels of Hypermedia Messages"[3] and talks about Structure-, Protocol-, and Application-level semantics.
I like this ... probably because it rather echoes the stuff I put into my own RO spec [1] (section 2.4, and figure 2).
-- dan
Jørn Wildt
Dec 16, 2012, 2:35:00 PM12/16/12
to hyperme...@googlegroups.com
Here is my two cents at the question: http://soabits.blogspot.dk/2012/04/restful-resources-are-not-typed.html
I think this quote from the post sums it up:
/Jørn
I think this quote from the post sums it up:
Instead of talking about "types" we can reframe our thinking and talk
about various views or facets of a resource - or perhaps the
capabilities it offers to a client interacting with it. Just make sure
you quit thinking of what the resource IS and think of what it can DO
for you instead.
Example; a client that has been given the task of printing a letter to the customer at some {Customer} URL can ask the resource at that URL to return a VCard such that the client can get a mailing address - and it couldn't care less if the resource was a cat, city, or movie actor, as long as it it was able to return a VCard when asked for it.
Example; a client that has been given the task of printing a letter to the customer at some {Customer} URL can ask the resource at that URL to return a VCard such that the client can get a mailing address - and it couldn't care less if the resource was a cat, city, or movie actor, as long as it it was able to return a VCard when asked for it.
/Jørn
Reply all
Reply to author
Forward
0 new messages