Loading ...
Sorry, an error occurred while loading the content.
 

Re: [rest-discuss] REST isn't hard to learn, it's just taught wrong.

Expand Messages
  • Eric J. Bowman
    ... I would like to think that there are enough experts on this list, yourself and myself included, to hash this sort of thing out without requiring Roy to
    Message 1 of 44 , Dec 23, 2009
      Stefan Tilkov wrote:
      >
      > 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
      > answer.
      >

      I would like to think that there are enough experts on this list,
      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:

      http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

      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
      RESTful systems:
      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
      protocol/API.

      ...

      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
      follow.

      -Eric
    • Eric J. Bowman
      ... I thought you were arguing against my assertion that *standard* media types provide protocol-level visibility, not just any old media type? ... While also
      Message 44 of 44 , Dec 26, 2009
        Subbu Allamaraju wrote:
        >
        > a. Media types provide protocol level visibility. This is
        > fundamental. I don't think I argued against this.
        >

        I thought you were arguing against my assertion that *standard* media
        types provide protocol-level visibility, not just any old media type?

        >
        > b. The Goodrelations ontology example below actually illustrates the
        > conventions I am referring to...
        >

        While also illustrating the danger posed. The example markup
        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=
        'ListedThing' content='foo'></span></span>.

        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>

        -Eric
      Your message has been successfully submitted and would be delivered to recipients shortly.