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

Less REST, more Hypermedia!

Expand Messages
  • Jakob Strauch
    We all know, many APIs and some frameworks* labelled with the term REST , do not support hypermedia (or less so called RESTful) mechanisms. The term is (and
    Message 1 of 10 , Dec 17, 2011
      We all know, many APIs and some frameworks* labelled with the term "REST", do not support hypermedia (or less so called RESTful) mechanisms. The term is (and likely will be) very overloaded in the IT industrie.

      I think, it is time to push forward terms like "hypermedia service/API" or "hypermedia-aware client". Instead of saying "hey i have a RESTful API", tell the people "i have a hypermedia API!".

      The term "hypermedia service" stands for** :

      - support of addressable resources
      - standard-conform usage of the uniform interface
      - (hopefully) a cleaner interface/interaction design
      - etc...


      IMHO, "hypermedia" is still a stepchild. It should be some kind of quality characteristic. What do you think?

      Jakob


      * I´m glad, the microsoft guys label their latest framework Web API (as opposed to the former WCF "REST" Starter Kit...)
      ** at least more than "REST"
    • Jan Algermissen
      ... My thinking has been and still is that part of the problem is that there are no names for non-REST but HTTP-based APIs. So we end up having to name a
      Message 2 of 10 , Dec 18, 2011
        On Dec 17, 2011, at 10:17 PM, Jakob Strauch wrote:

        > We all know, many APIs and some frameworks* labelled with the term "REST", do not support hypermedia (or less so called RESTful) mechanisms. The term is (and likely will be) very overloaded in the IT industrie.
        >
        > I think, it is time to push forward terms like "hypermedia service/API" or "hypermedia-aware client". Instead of saying "hey i have a RESTful API", tell the people "i have a hypermedia API!".
        >
        > The term "hypermedia service" stands for** :
        >
        > - support of addressable resources
        > - standard-conform usage of the uniform interface
        > - (hopefully) a cleaner interface/interaction design
        > - etc...
        >
        > IMHO, "hypermedia" is still a stepchild. It should be some kind of quality characteristic. What do you think?

        My thinking has been and still is that part of the problem is that there are no names for non-REST but HTTP-based APIs. So we end up having to name a non-REST API using the word REST and explaining what is *not* in there. But this causes REST to be burned into the readers mind...even if we talk about non REST APIs.

        I tried to fix that with this http://www.nordsc.com/ext/classification_of_http_based_apis.html a while ago. Based on that I can now say that some API is 'HTTP Type I' so the beast gets a proper name :-)

        JAn



        >
        > Jakob
        >
        > * I´m glad, the microsoft guys label their latest framework Web API (as opposed to the former WCF "REST" Starter Kit...)
        > ** at least more than "REST"
        >
        >
      • Jason Erickson
        I have seen this and found it to be quite helpful. I was wondering whether you consider XHTML a generic or specific media type for the purposes of your
        Message 3 of 10 , Dec 18, 2011
          I have seen this and found it to be quite helpful. I was wondering whether you consider XHTML a generic or specific media type for the purposes of your categorization.

          On Dec 18, 2011, at 1:47 AM, Jan Algermissen <jan.algermissen@...> wrote:

          >
          > My thinking has been and still is that part of the problem is that there are no names for non-REST but HTTP-based APIs. So we end up having to name a non-REST API using the word REST and explaining what is *not* in there. But this causes REST to be burned into the readers mind...even if we talk about non REST APIs.
          >
          > I tried to fix that with this http://www.nordsc.com/ext/classification_of_http_based_apis.html a while ago. Based on that I can now say that some API is 'HTTP Type I' so the beast gets a proper name :-)
          >
          > JAn
          >
          >
          >
          >>
          >> Jakob
          >>
          >> * I´m glad, the microsoft guys label their latest framework Web API (as opposed to the former WCF "REST" Starter Kit...)
          >> ** at least more than "REST"
          >>
          >>
          >
          >
          >
          > ------------------------------------
          >
          > Yahoo! Groups Links
          >
          >
          >
        • Jan Algermissen
          ... Thanks. ... XHTML is a specific media type. (It provides all the semantics to implement such very specific products known as browsers :-) However, beware
          Message 4 of 10 , Dec 18, 2011
            On Dec 18, 2011, at 6:49 PM, Jason Erickson wrote:

            > I have seen this and found it to be quite helpful.

            Thanks.

            > I was wondering whether you consider XHTML a generic or specific media type for the purposes of your categorization.

            XHTML is a specific media type. (It provides all the semantics to implement such very specific products known as browsers :-)

            However, beware that this does not mean that adding out-of-band constraints to XHTML (e.g. presence of certain div with certain classes) is 'ok' from a REST POV. Such out-of-band agreements still violate the message self descriptiveness constraint.

            What I think is a nice way to leverage XHTML is to mint your own media type that specifically documents your refinements. That way, you can serve one and the same entity as application/xhtml and application/vnd.my.new.mediatype, depending on the Accept header of the client.

            Jan

            >
            > On Dec 18, 2011, at 1:47 AM, Jan Algermissen <jan.algermissen@...> wrote:
            >
            > >
            > > My thinking has been and still is that part of the problem is that there are no names for non-REST but HTTP-based APIs. So we end up having to name a non-REST API using the word REST and explaining what is *not* in there. But this causes REST to be burned into the readers mind...even if we talk about non REST APIs.
            > >
            > > I tried to fix that with this http://www.nordsc.com/ext/classification_of_http_based_apis.html a while ago. Based on that I can now say that some API is 'HTTP Type I' so the beast gets a proper name :-)
            > >
            > > JAn
            > >
            > >
            > >
            > >>
            > >> Jakob
            > >>
            > >> * I´m glad, the microsoft guys label their latest framework Web API (as opposed to the former WCF "REST" Starter Kit...)
            > >> ** at least more than "REST"
            > >>
            > >>
            > >
            > >
            > >
            > > ------------------------------------
            > >
            > > Yahoo! Groups Links
            > >
            > >
            > >
            >
          • mike amundsen
            ... I often use XHTML as a media-type base and express problem domain specifics using @id, @name, @class, @rel. I document this usage in a
            Message 5 of 10 , Dec 18, 2011
              <snip>
              > However, beware that this does not mean that adding out-of-band constraints to XHTML (e.g. presence of certain div with certain classes) is 'ok' from a REST POV. Such out-of-band agreements still violate the message self descriptiveness constraint.
              </snip>

              I often use XHTML as a media-type "base" and express problem domain
              specifics using @id, @name, @class, @rel. I document this usage in a
              manner similar to documenting custom media types[1] and publish this
              data as a "profile"[2] for [X]HTML.

              This allows developers (client and server) to "follow the media type"
              and produce messages that are "self-descriptive" regarding possible
              options within the context of each response representation. In this
              way, the "information becomes the affordance"[3].

              From my POV, this approach follows Fielding's suggestions on crafting
              hypertext APIs[4] (see bullet #3).

              I've written a handful of 'bots (M2M solutions) using this approach, too.

              [1] http://amundsen.com/hypermedia/profiles/
              [2] http://gmpg.org/xmdp/
              [3] http://www.w3.org/wiki/AffordanceReferences
              [4] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

              mca
              http://amundsen.com/blog/
              http://twitter.com@mamund
              http://mamund.com/foaf.rdf#me




              On Sun, Dec 18, 2011 at 13:04, Jan Algermissen
              <jan.algermissen@...> wrote:
              >
              > On Dec 18, 2011, at 6:49 PM, Jason Erickson wrote:
              >
              >> I have seen this and found it to be quite helpful.
              >
              > Thanks.
              >
              >> I was wondering whether you consider XHTML a generic or specific media type for the purposes of your categorization.
              >
              > XHTML is a specific media type. (It provides all the semantics to implement such very specific products known as browsers :-)
              >
              > However, beware that this does not mean that adding out-of-band constraints to XHTML (e.g. presence of certain div with certain classes) is 'ok' from a REST POV. Such out-of-band agreements still violate the message self descriptiveness constraint.
              >
              > What I think is a nice way to leverage XHTML is to mint your own media type that specifically documents your refinements. That way, you can serve one and the same entity as application/xhtml and application/vnd.my.new.mediatype, depending on the Accept header of the client.
              >
              > Jan
              >
              >>
              >> On Dec 18, 2011, at 1:47 AM, Jan Algermissen <jan.algermissen@...> wrote:
              >>
              >> >
              >> > My thinking has been and still is that part of the problem is that there are no names for non-REST but HTTP-based APIs. So we end up having to name a non-REST API using the word REST and explaining what is *not* in there. But this causes REST to be burned into the readers mind...even if we talk about non REST APIs.
              >> >
              >> > I tried to fix that with this http://www.nordsc.com/ext/classification_of_http_based_apis.html a while ago. Based on that I can now say that some API is 'HTTP Type I' so the beast gets a proper name :-)
              >> >
              >> > JAn
              >> >
              >> >
              >> >
              >> >>
              >> >> Jakob
              >> >>
              >> >> * I´m glad, the microsoft guys label their latest framework Web API (as opposed to the former WCF "REST" Starter Kit...)
              >> >> ** at least more than "REST"
              >> >>
              >> >>
              >> >
              >> >
              >> >
              >> > ------------------------------------
              >> >
              >> > Yahoo! Groups Links
              >> >
              >> >
              >> >
              >>
              >
              >
              >
              > ------------------------------------
              >
              > Yahoo! Groups Links
              >
              >
              >
            • Erik Mogensen
              On Sun, Dec 18, 2011 at 7:04 PM, Jan Algermissen
              Message 6 of 10 , Dec 19, 2011
                On Sun, Dec 18, 2011 at 7:04 PM, Jan Algermissen <jan.algermissen@...> wrote:
                What I think is a nice way to leverage XHTML is to mint your own media type that specifically documents your refinements. That way, you can serve one and the same entity as application/xhtml and application/vnd.my.new.mediatype, depending on the Accept header of the client.

                +1 :-)
                -- 
                -mogsie-
              • Alessandro Nadalin
                ... +27.000 :) I thought I was the only one saying hypermedia-aware clients . That s what I m already doing since some months: since the REST term has been
                Message 7 of 10 , Dec 19, 2011
                  On Sat, Dec 17, 2011 at 10:17 PM, Jakob Strauch <jakob.strauch@...> wrote:
                   

                  We all know, many APIs and some frameworks* labelled with the term "REST", do not support hypermedia (or less so called RESTful) mechanisms. The term is (and likely will be) very overloaded in the IT industrie.

                  I think, it is time to push forward terms like "hypermedia service/API" or "hypermedia-aware client". Instead of saying "hey i have a RESTful API", tell the people "i have a hypermedia API!".


                  +27.000 :)

                  I thought I was the only one saying "hypermedia-aware clients".
                  That's what I'm already doing since some months: since the REST term has been raped during the last decade I am now talking about HTTP (doh) and Hypermedia API.

                  It's quite disappointing, but you'll notice that a few people will ask you "why hypermedia" or "why not REST", so, at least, they're gonna dig a bit about that.
                   


                  The term "hypermedia service" stands for** :

                  - support of addressable resources
                  - standard-conform usage of the uniform interface
                  - (hopefully) a cleaner interface/interaction design
                  - etc...

                  IMHO, "hypermedia" is still a stepchild. It should be some kind of quality characteristic. What do you think?

                  Jakob

                  * I´m glad, the microsoft guys label their latest framework Web API (as opposed to the former WCF "REST" Starter Kit...)
                  ** at least more than "REST"




                  --
                  Nadalin Alessandro
                  www.odino.org
                  www.twitter.com/_odino_

                • Paul Cohen
                  Hi, On Mon, Dec 19, 2011 at 12:22 PM, Alessandro Nadalin ... Yes. that s nice. ... I ve thought about this naming issue too, and agree that a lot of the
                  Message 8 of 10 , Dec 19, 2011
                    Hi,

                    On Mon, Dec 19, 2011 at 12:22 PM, Alessandro Nadalin
                    <alessandro.nadalin@...> wrote:
                    > On Sat, Dec 17, 2011 at 10:17 PM, Jakob Strauch <jakob.strauch@...> wrote:
                    >> We all know, many APIs and some frameworks* labelled with the term "REST", do not support hypermedia (or less so called RESTful) mechanisms. The term is (and likely will be) very overloaded in the IT industrie.
                    >>
                    >> I think, it is time to push forward terms like "hypermedia service/API" or "hypermedia-aware client". Instead of saying "hey i have a RESTful API", tell the people "i have a hypermedia API!".
                    > +27.000 :)

                    Yes. that's nice.

                    > I thought I was the only one saying "hypermedia-aware clients".
                    > That's what I'm already doing since some months: since the REST term has been raped during the last decade I am now talking about HTTP (doh) and Hypermedia API.

                    I've thought about this naming issue too, and agree that a lot of the
                    discussions regarding REST-fulness of API:s are rather ... tiring.
                    Here's my 5c on the name game.

                    The HT-part of HTTP is actually a bit of a misnomer. Hypertext has
                    already been superseeded by hypermedia. mayby the time has come to
                    talk of Hyperresources?

                    I do think "hypermedia service/API" is nice but what about:

                    Hyperlinked Resource Transfer Service

                    I do realize that HyRTS is not a good acronym. Maybe we could just
                    call it a Web Service? Oh wait, that name has already been highjacked
                    by a technology that's not really Web-oriented ...hmm ... I think I'll
                    go back to coding.

                    /Paul

                    --
                    Paul Cohen
                    www.seibostudios.se
                    mobile: +46 730 787 035
                    e-mail: paul.cohen@...
                  • Glenn Block
                    Sebastian Lambla and I were discussing this at QCON London. The advantage of hypermedia service/api as a term is that is not something the pop culture REST
                    Message 9 of 10 , Dec 20, 2011
                      Sebastian Lambla and I were discussing this at QCON London. The advantage of hypermedia service/api as a term is that is not something the pop culture REST crowd cares about. The downside of attaching everything to that term ls that hypermedia is just one of several constraints, and just because you have a hypermedia based api, it does not mean you are RESTFul, though the reverse is true.

                      I do see value in some new differentiated term based on the pop culture usage / misconceptions around REST.

                      It would be so much easier of HTTP api or web api was the term used for those services, but REST is too sexy.

                      Sent from my Windows Phone

                      From: Paul Cohen
                      Sent: 12/19/2011 4:36 AM
                      To: Alessandro Nadalin
                      Cc: Jakob Strauch; rest-discuss@yahoogroups.com
                      Subject: Re: [rest-discuss] Less REST, more Hypermedia!

                       

                      Hi,

                      On Mon, Dec 19, 2011 at 12:22 PM, Alessandro Nadalin
                      <alessandro.nadalin@...> wrote:

                      > On Sat, Dec 17, 2011 at 10:17 PM, Jakob Strauch <jakob.strauch@...> wrote:
                      >> We all know, many APIs and some frameworks* labelled with the term "REST", do not support hypermedia (or less so called RESTful) mechanisms. The term is (and likely will be) very overloaded in the IT industrie.
                      >>
                      >> I think, it is time to push forward terms like "hypermedia service/API" or "hypermedia-aware client". Instead of saying "hey i have a RESTful API", tell the people "i have a hypermedia API!".
                      > +27.000 :)

                      Yes. that's nice.

                      > I thought I was the only one saying "hypermedia-aware clients".
                      > That's what I'm already doing since some months: since the REST term has been raped during the last decade I am now talking about HTTP (doh) and Hypermedia API.

                      I've thought about this naming issue too, and agree that a lot of the
                      discussions regarding REST-fulness of API:s are rather ... tiring.
                      Here's my 5c on the name game.

                      The HT-part of HTTP is actually a bit of a misnomer. Hypertext has
                      already been superseeded by hypermedia. mayby the time has come to
                      talk of Hyperresources?

                      I do think "hypermedia service/API" is nice but what about:

                      Hyperlinked Resource Transfer Service

                      I do realize that HyRTS is not a good acronym. Maybe we could just
                      call it a Web Service? Oh wait, that name has already been highjacked
                      by a technology that's not really Web-oriented ...hmm ... I think I'll
                      go back to coding.

                      /Paul

                      --
                      Paul Cohen
                      www.seibostudios.se
                      mobile: +46 730 787 035
                      e-mail: paul.cohen@...

                    • Moore, Jonathan (CIM)
                      Hi Jakob, Funny you should mention it: this was a punchline at the end of my RESTFest keynote in August. You can jump in to 3:30 of this video of it for this
                      Message 10 of 10 , Dec 20, 2011
                        Hi Jakob,

                        Funny you should mention it: this was a punchline at the end of my RESTFest keynote in August. You can jump in to 3:30 of this video of it for this exact discussion:


                        I used the phrase "REST has jumped the shark" to describe the fact that common understanding of REST is "use HTTP as your application protocol" and that's it. No amount of "you're doing REST wrong" or "you're doing REST-minus-minus" will actually make headway against this now.

                        On the other hand, "hypermedia APIs" are something new to most people--it's actually easier to get people to look at something new they're not doing than to try to tell them they're not doing all of what they thought they were doing. I think this is a better approach to get people to look at "the rest of REST" they're missing.

                        Jon
                        ........
                        Jon Moore
                        Comcast Interactive Media



                        From: Jakob Strauch <jakob.strauch@...>
                        Date: Sat, 17 Dec 2011 21:17:42 +0000
                        To: <rest-discuss@yahoogroups.com>
                        Subject: [rest-discuss] Less REST, more Hypermedia!

                         

                        We all know, many APIs and some frameworks* labelled with the term "REST", do not support hypermedia (or less so called RESTful) mechanisms. The term is (and likely will be) very overloaded in the IT industrie.

                        I think, it is time to push forward terms like "hypermedia service/API" or "hypermedia-aware client". Instead of saying "hey i have a RESTful API", tell the people "i have a hypermedia API!".

                        The term "hypermedia service" stands for** :

                        - support of addressable resources
                        - standard-conform usage of the uniform interface
                        - (hopefully) a cleaner interface/interaction design
                        - etc...

                        IMHO, "hypermedia" is still a stepchild. It should be some kind of quality characteristic. What do you think?

                        Jakob

                        * I´m glad, the microsoft guys label their latest framework Web API (as opposed to the former WCF "REST" Starter Kit...)
                        ** at least more than "REST"

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