Fwd: [rest-discuss] Re: A RESTful Hypermedia API
- The uniform interface belongs to the protocol, not the media type. This post is about designing a media-type. It is my assertion that mapping the media-type's hypermedia links to a particular protocol is an implementation detail.I agree that some media-types assume a particular primary protocol (e.g. HTML assumes HTTP) and that media-type's documentation reflects this assumption . However, I do not think all media types must claim a primary protocol in order to be valid.I'd like to hear from others on this idea.- MUST a media-type assume a primary protocol and reflect that in the documentation?- SHOULD a media-type identify a primary protocol and reflect that in the documentation?More to the point, is the idea of a true protocol-agnostic media-type meaningless? unhelpful?Thanks. http://www.whatwg.org/specs/web-apps/current-work/multipage/association-of-controls-and-forms.html#constructing-form-data-set (see step 15)2010/4/7 António Mota <amsmota@...>
But isn't that the wrong approach to REST and one of the reasons that is so wrongly interpreted and worse implemented? (and I'm not implying that I know the correct one, far from it, actually the more I read this list the more I think I don;t know nothing about it)
What I mean is, shouldn't REST be approached as a different paradigm than RPC, not only different but incompatible? It reminds me a lot when I started using XSLT, the different "way of thought" you have to have if you come from a procedural or a oo field? At some point I acted almost if I have a switch inside my head, turn on for XSLT, turn off for Java...
From this point of view, the approach of the article is from the point of view of RPC all right, like "How I Explain REST To My RPC Friend", but from a REST point of view, shouldn't the approach be precisely the opposite sequence of that taken in the article?
First, decide your Uniform Interface
Second, define your media-types
Third, define your Resources
And leave the API's well hidden behind the server, as a mere implementation detail, and *never* show it to the clients/user-agents...
Melhores cumprimentos / Beir beannacht / Best regards
António Manuel dos Santos Mota
On 7 April 2010 14:28, William Martinez Pomares <wmartinez@...> wrote:
I partially agree with the naming issues.
But I see it under a different light.
See, this post is developer driven, thought to get the dev into code in three simple steps. Haven't read it in deep, just over read, and I see first that we try the API as a normal RPC API to begin with. Then we go into defining what we need, for instance a data structure, that is not more that a resource actual representation.
All that is fine for me, but I feel it needs the mapping explanation. Since I come from the architectural side, I would start by defining why we need the API, and how the API is RESTFull in the REST sense. Then I may come with this regular API and explain what changes should I make to create a RESTFull one. Then I explain what the resources would be (a data dictionary fits fine), and then the possible representations (structure) and then etc.
This is more work, I know, and probably a developer wants to have the code to just copy paste, but if we intend to teach about REST I would suggest to include the what (concept) and then the how (in dev terms). In other words, do not replace, add.
Will read it in calm and post more about it later.
William Martinez Pomares
--- In firstname.lastname@example.org, Tim Williams <williamstw@...> wrote:
> 2010/4/6 António Mota <amsmota@...>
> > You're going to be pissed with me because I didn't even read the entire article (I'll do it at home
> > tonigth) but after reading this sentence
> > "this API will define a simple list management service."
> > and since I just said in another post that IMO "API" and "service" should not be used to describe
> > REST, I tried this simple semantic analysis
> > CTRL+F resource
> > and no single result was found!
> > Now, should a description of a REST-something have more emphasis in "resources" rather than
> > "services"? It can be just a question of "naming", but is not a important one?
> I'd extend this comment to say it'd be better if it stuck to
> resource/representations instead of using 'data structure' that sort
> of blurs the two. This too may seem nit-picky but using imprecise
> terminology just raises the communication overhead I think.
- On Apr 7, 2010, at 4:14 PM, mike amundsen wrote:I believe in the general case, a media type should identify the protocol(s) it's supposed to work with (and how it does so) for simple practical reasons, even though I tend to believe that this is somewhat unRESTful.Excuse me while I cry for an hour about this style of spec writing.Stefan--Stefan Tilkov, http://www.innoq.com/blog/st/
- On 7 April 2010 15:14, mike amundsen <mamund@...> wrote:The uniform interface belongs to the protocol, not the media type.
Well, from my point of view, based only from a practical experience we had building a "midleware" based on a REST approach, that can't be the case. Basically because when I refered a "protocol agnostic" I was thinking not only agnostic but in "multi protocol" architecture.
If the same application (meaning the same set of resources) are to be referenced by both HTTP and FTP, how can you have then two different Uniform Interface for that same application?
So what I was saying is, in a situation like that, you should have:
Application Uniform Interface (any names you want, these are just invented)
FETCH, ATTACK, KILL
in HTTP you translate that to
GET, POST, DELETE
in FTP, to
RETR, STOR, DELE
the translations being made by the specific connector, HTTPConnector, FTPConnector, etc...
Otherwise you can't have a multi-protocol application, or having it you break the Uniform Interface constraint...
- On Apr 7, 2010, at 7:20 AM, Stefan Tilkov wrote:
>>LOL. It is like C code explained in English.
>>  http://www.whatwg.org/specs/web-apps/current-work/multipage/association-of-controls-and-forms.html#constructing-form-data-set (see step 15)
> Excuse me while I cry for an hour about this style of spec writing.
- mike amundsen wrote:
> MUST a media-type assume a primary protocol andNo.
> reflect that in the documentation?
> SHOULD a media-type identify a primary protocolNo.
> and reflect that in the documentation?
> More to the point, is the idea of a true protocol-agnosticNot meaningless at all. HTML documents have meaning even when they're
> media-type meaningless? unhelpful?
sitting around on disk, not being transferred over a network protocol.
This meaning and the syntax that communicates it belong in the
media-type specification. Network protocol constraints belong in
protocol specifications. For example, AtomPub (RFC 5023) defines two new
media-types, but it is not itself a media type, it's a publishing
protocol. Perhaps AtomPub is doing itself a disservice defining new
types in the same draft wherein it defines a new application protocol?
Hmm. Maybe I should split Shoji's media type into a separate document...