Re: [rest-discuss] REST isn't hard to learn, it's just taught wrong.
- Stefan Tilkov wrote:
>I would like to think that there are enough experts on this list,
> I understand your viewpoint to be that anything not publicly
> standardized (i.e. a custom link relation, or media type, or verb) is
> by definition not RESTful. I don't think so, but of course I may be
> wrong - in my view, you can standardize e.g. within your company or
> some other domain. Probably we need Roy to provide an authoritative
yourself and myself included, to hash this sort of thing out without
requiring Roy to referee. Besided, I do believe Roy explained this
point until he was blue in the face, in the comments here:
I recommend reading the entire comment thread, to put my excerpts in
their proper context. In the context of using standardized media
types, Roy has plenty to say...
To some extent, people get REST wrong because I failed to include
enough detail on media type design within my dissertation...
You don't get to decide what POST means -- that is decided by the
resource. Its purpose is supposed to be described in the same context
in which you found the URI that you are posting to. Presumably, that
context (a hypertext representation in some media type understood by
your client) tells you or your agent what to expect from the POST using
some combination of standard elements/relations and human-readable
text. The HTTP response will tell you what happened as a result...
Perhaps [this comment] will help clarify the role of standards in
Of course the client has prior knowledge. Every protocol, every media
type definition, every URI scheme, and every link relationship type
constitutes prior knowledge that the client must know (or learn) in
order to make use of that knowledge. REST doesn't eliminate the need
for a clue. What REST does is concentrate that need for prior knowledge
into readily standardizable forms. That is the essential distinction
between data-oriented and control-oriented integration.
It has value because it is far easier to standardize representation and
relation types than it is to standardize objects and object-specific
interfaces. In other words, there are fewer things to learn and they
can be recombined in unanticipated ways while remaining understandable
to the client.
In terms of testing a specification, the hardest part is identifying
when a RESTful protocol is actually dependent on out-of-band
information... What I look for are requirements on processing behavior
that are defined outside of the media type specification. One of the
easiest ways to see that is when a protocol calls for the use of a
generic media type (like application/xml or application/json) and then
requires that it be processed in a way that is special to the
The media type identifies a specification that defines how a
representation is to be processed. That is out-of-band information (all
communication is dependent on some prior knowledge). What you are
missing is that each representation contains the specific instructions
for interfacing with a given service, provided in-band. The media type
is a generic processing model that every agent can learn if there
aren't too many of them (hence the need for standards).
The only thing Roy describes as acceptably domain-specific, are
vocabularies contained within standard media types:
"Exposing that vocabulary in the representations makes it easy to learn
and be adopted by others. Some of it will be standardized, some of it
will be domain-specific, but ultimately the agents will have to be
adaptable to new vocabulary.
I hope this is all the backing I need for my stance: this list is full
of examples given in terms of URIs, HTTP methods and response codes,
and hypothetical media types with a target audience of a single
system. We need to stop doing this, or at least point out that to do
so is fundamentally at odds with the REST style, and stress using
standard (or at least standardizable) media types, because method use
must be encompassed within the definition of the media type.
Otherwise, the REST community is just as responsible as the API
designers, for the sorry state of affairs where 99% of REST APIs don't
conform to the style. I believe this is a solid foundation for my
hypothesis that we're teaching REST wrong. "Rebooting REST" thread to
- Subbu Allamaraju wrote:
>I thought you were arguing against my assertion that *standard* media
> a. Media types provide protocol level visibility. This is
> fundamental. I don't think I argued against this.
types provide protocol-level visibility, not just any old media type?
>While also illustrating the danger posed. The example markup
> b. The Goodrelations ontology example below actually illustrates the
> conventions I am referring to...
represents a most hideous abuse of the HTML host language. I've never
seen a <span> wrapping other, indented <span>s referred to as
"structured markup" before. The native semantics of HTML are used to
create structured markup, i.e. a list of items is a <ul> element
wrapping <li> elements -- providing block-element structure that
doesn't rely on indenting. The <span> element is an inline element, no
matter if there is a line break or indentation or, forfend, <br/> (a
mostly-irrelevant element in light of CSS) separating them.
I haven't studied GoodRelations enough yet, but I certainly hope they
haven't specified this crazy approach to semantic-free HTML markup.
They also present a horrific example of bad table markup, inaccessible
in any way to assistive devices that can't interpret GoodRelations
ontology, instead of gracefully degrading or providing enhancement to
existing accessible, semantic markup. My fear is that things move in a
direction where standard element semantics <ul> and <li> are utterly
ignored in favor of metadata <span typeof='ListOfThings'><span typeof=
Start with a semantically marked-up table that uses accessibility
attributes, _then_ enhance it to include GoodRelations metadata,
instead of throwing out semantic, accessible markup in favor of cryptic
metadata presented in tags like <span> which have no semantics or
structure, to show a <table> of open/close times by day-of-week.
GoodRelations also fails to put content inside of elements, instead
tucking it away inside of attributes. Metadata attributes should be
used to describe element content, not attribute content. IMNSHO.
Which is why I stated that GoodRelations only shows us what is
possible, not what is desirable. </rant>