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

REST is not about domain models

Expand Messages
  • Jørn Wildt
    If REST is not about domain models (as Glenn Block states it here: http://tech.groups.yahoo.com/group/rest-discuss/message/18117) how are we then going to
    Message 1 of 20 , Dec 21, 2011
      If "REST is not about domain models" (as Glenn Block states it here:
      http://tech.groups.yahoo.com/group/rest-discuss/message/18117) how are we
      then going to solve machine-to-machine scenarious where it is all about
      specific domains? By not using REST? I know this is beating an old horse,
      but I still have issues with the idea of ignoring the domain of a system.

      I do se the benefits of not serializing internal object representations
      directly. That would expose the inner workings of the system. So adding some
      kind of public facing representation on top of it makes sense. Then you can
      freely change the inner workings without worrying about the clients (as long
      as you keep the transformation to the public representation in sync).

      What I do not understand is the fear of coupling the clients to the domain.
      I mean: if I am creating an M2M system working with e-commerce then it must
      surely understand what a quote, a sales order, a bill, and a payment is?
      Never mind what format these entities are represented in - if it's HTML than
      the client must have decoders for RDFa -> Quote/Order/Bill/whatever, and
      similar for XML, HAL, CSV and whatever other format one might choose. In the
      end the client must be able to decode from the wire format (public
      representation) to some kind of internal object representing the domain on
      the client side, such that it can do actual operations on it.

      So, as I see it, we cannot avoid some kind of decoding/deserialization on
      the client, where it will take the public representation and convert it to
      some internal domain specific representation - thereby coupling the client
      to the domain. What is it that I am failing to understand here?

      But maybe I am too single minded ... the systems I work with are all about
      M2M integrations, where one sub-system is reading data from another
      sub-system and then making decisions based on that data (meaning they must
      have some sort of domain understanding). In these cases we need to expose
      domain data, and the formats for that are usually vendor specifik
      derivations of XML or JSON. It could of course be possible to use PDF as a
      public format, but that would make it rather difficult to automatically
      extract the required domain specific data.

      Regards, Jørn
    • Jørn Wildt
      I just finished reading the advertise media types thread. And Eric and Mike hits exactly where it hurts :-) See
      Message 2 of 20 , Dec 21, 2011
        I just finished reading the "advertise media types" thread. And Eric and
        Mike hits exactly where it hurts :-) See
        http://tech.groups.yahoo.com/group/rest-discuss/message/18127:

        Mike> each time a dev
        > spits out custom XML or JSON serializations of internal objects, a
        > "new media type" is born (and i think someone kicks a cat, too).
        >
        Eric> Yeah, that would be me...

        Which leaves me with that feeling of "yes, I am not ignorant, I hear what
        you are saying, but apparently I am blind for the alternatives". There are
        endless numbers of different domains out there: we can fit it all into HTML
        for humans to read (the web has proven that already), but I cannot see how
        we can make clients for M2M interaction without hardwiring domain knowledge
        into them?

        As Paul states it "The web is not recompiled every morning - yet it works!".
        Sure! But we do not recompile it because humans are so good at adopting to
        whatever they see on a screen. But for a M2M system to work it surely must
        be recompiled in order to understand new or changed semantics of the domain
        it works with. Yes, it can be built such that new features are ignored by
        old clients and that is certainly worth striving for - but new clients are
        needed for new semantics.

        /Jørn
      • Jan Algermissen
        ... Spot on :-) You must hard-wire domain knowledge into clients or communication won t happen. No matter how generic your media types is, you always end up
        Message 3 of 20 , Dec 21, 2011
          On Dec 22, 2011, at 7:50 AM, Jørn Wildt wrote:

          > but I cannot see how
          > we can make clients for M2M interaction without hardwiring domain knowledge
          > into them?

          Spot on :-) You must hard-wire domain knowledge into clients or communication won't happen. No matter how generic your media types is, you always end up putting in your code the knowledge about the domain.

          What REST changes is who *owns* the contact. In RPC systems, the contract is owned entirely by the server, allowing it to change the contract at will as long as it considers the effect on existing clients.

          REST moves the contract away from the server to a 'global ownership' (e.g. IANA)[1] effectively leading two two things:

          1. The server cannot change the contract at will; not without engaging into a
          form of global communication about the change. Therefore server owners cannot
          (by nature of the system) break clients - the contract cannot change all of
          a sudden.

          2. In order for servers to evolve without changing the global contract every time
          the contract (i.e. media types) must allow for a certain amount of change.
          This 'allowing for a certain amount of change' leads to greater client-side
          development efforts - clients must be programmed to cope with the possible
          changes enabled by the media types the clients implements.

          [1] 'Global' need not be world-wide. It can very well just mean 'global to your
          enterprise' (for integration scenarios) - what matters is that no individual
          servers own the contract but that in independent (for any definition of independent)
          party is responsible.

          >
          > As Paul states it "The web is not recompiled every morning - yet it works!".
          > Sure! But we do not recompile it because humans are so good at adopting to
          > whatever they see on a screen. But for a M2M system to work it surely must
          > be recompiled in order to understand new or changed semantics of the domain
          > it works with.

          No, this is not true thanks to content negotiation and well designed
          extension rules for payload formats.

          The cases where a server needs to switch from application/procurement-v1 to
          application/procurement-v2 instantly, without a transition period of supporting
          those application/procurement-v1 enabled clients is extremely rare. (Feel free to
          construct an example).

          The cool thing about REST is that any form of evolution can take place without
          coordinating the change between clients, servers and intermediaries. It can even
          happen without terminating *current* business transactions between clients and
          servers. E.g. I can buy a book at Amazon at the same time they change their
          system - or when was the last time you had to stop a purchase because of an
          ongoing update?

          This is so natural to use Web users and I continue to find it astonishing that
          business systems owners are not jumping like mad on that feature regarding their
          internal IT systems.

          Some start to get it, often in combination with agility goals but the majority is
          still lightyears 'behind'.


          > Yes, it can be built such that new features are ignored by
          > old clients and that is certainly worth striving for - but new clients are
          > needed for new semantics.

          Yes, sure. But that is a property of networked systems regardless of architectural
          style.

          Jan


          >
          > /Jørn
          >
          >
        • Jorn Wildt
          ... Okay. That (and the rest you wrote) makes good sense. But I still feel sorry for the cats that get kicked when someone mints a new media type. ...
          Message 4 of 20 , Dec 22, 2011
            > What REST changes is who *owns* the contact.

            > [1] 'Global' need not be world-wide. It can very well just mean 'global to your enterprise'

            Okay. That (and the rest you wrote) makes good sense. But I still feel sorry for the cats that get kicked when someone mints a new media type.

            And, just to make it clear, by this:

            > > Yes, it can be built such that new features are ignored by
            > > old clients

            I was referring to the idea of conneg and versioning you mention here:

            > No, this is not true thanks to content negotiation and well designed
            > extension rules for payload formats.

            Unfortunately I wasn't clear about it.

            /Jørn
          • Jan Algermissen
            ... Why? In an intra-enterprise context, the activity is not much different from designing some service s XML[1]. You only need to take that extra mile and
            Message 5 of 20 , Dec 22, 2011
              On Dec 22, 2011, at 9:05 AM, Jorn Wildt wrote:

              > > What REST changes is who *owns* the contact.
              >
              > > [1] 'Global' need not be world-wide. It can very well just mean 'global to your enterprise'
              >
              > Okay. That (and the rest you wrote) makes good sense. But I still feel sorry for the cats that get kicked when someone mints a new media type.

              Why? In an intra-enterprise context, the activity is not much different from designing some service's XML[1]. You only need to take that extra mile and make it global (and media type-ish instead of POX-ish of course). And sure, in m2m contexts, you have to take care not to suffer media type bloat. OTH, the latter will be much better than XML schema and RPC-API bloat. REST-based thinking helps a lot to look outside the fence of your own current server implementation task.

              I'd prefer a hundred media types over a hundred SOAP APIs every time...besides, it is much more fun to design the former :-)

              (You won't be able to do e.g. enterprise integration with HTML semantics only)

              Jan

              [1] I found that usually, some perceived service (and percived 'canonical' application) is the starting point for designing a media type.

              >
              > And, just to make it clear, by this:
              >
              > > > Yes, it can be built such that new features are ignored by
              > > > old clients
              >
              > I was referring to the idea of conneg and versioning you mention here:
              >
              > > No, this is not true thanks to content negotiation and well designed
              > > extension rules for payload formats.
              >
              > Unfortunately I wasn't clear about it.
              >
              > /Jørn
              >
              >
            • Jorn Wildt
              ... Not because I am going to kick them, I believe myself to be completely aligned with your opinion. It s just that Mike and Eric s comment
              Message 6 of 20 , Dec 22, 2011
                > > Okay. That (and the rest you wrote) makes good sense. But I still feel sorry for the cats that get kicked when someone mints a new media type.
                >
                > Why?

                Not because I am going to kick them, I believe myself to be completely aligned with your opinion. It's just that Mike and Eric's comment (http://tech.groups.yahoo.com/group/rest-discuss/message/18127), about kicking a cat every time a new media type is minted, is contrary to your view on media types. They may although be referring to different scenarios?

                > And sure, in m2m contexts, you have to take care not to suffer media type bloat. OTH, the latter will be much better than XML schema and RPC-API bloat.

                Yes, having a (enterprise) central definition of a quote representation must be way better than ten different departments having each their own SOAP/schema for that.

                Thanks, Jørn
              • Jan Algermissen
                ... One thing I forgot to say: There is a difference between protocol and service functionality and a client needs to consider two things: Why it chooses a
                Message 7 of 20 , Dec 22, 2011
                  On Dec 22, 2011, at 7:50 AM, Jørn Wildt wrote:

                  > There are
                  > endless numbers of different domains out there

                  One thing I forgot to say:

                  There is a difference between protocol and service functionality and a client needs to consider two things: Why it chooses a specific service and how to interact with it.

                  The service type is orthogonal to the question of what API it exposes (there might even be several APIs in serveral arch. styles on a single service). This is an aspect that is in my experience not well understood nor talked about. Certainly the SOA(P) world completely ignores this distinction, often implicitly substituting service API signature with service type.

                  Many of the domain semantics you mention can be part of the service types defined in that domain. Client (of course) need to understand these service types to make the very decision *which* service to talk to to achieve a certain goal. This decision includes quite some amount of expectations about how the service will behave (sometimes referred to as 'intent').

                  Media types only need to capture the protocol semantics that enable communication they need not (and must not) define service functionality.

                  This is why you do not need an <order-placement-request> XML schema (or a placeOrder() method for that matter) - it is sufficient, for example, to base the actual communication on a domain-independent media type spec such as AtomPub and POST <order>s to an AtomPub server *that whoever configures the application knows to be an order-processing-service*.

                  You can see this in code, if you consider that

                  OrderProcessorService ops;
                  Order order;
                  ...
                  ops.placeOrder(order);

                  unnecessarily duplicates the knowledge how ops behaves into the RPC API ( => placeOrder(Order order)).

                  OrderProcessorService ops;
                  Order order;
                  ...
                  ops.post(order);

                  does exactly the same thing but this time through a uniform API.

                  -----

                  If you point your browser to Amazon to buy a book, you pick Amazon's service because you expect to be able to order books there. Your HTTP/HTML based browser is just an agent (sic!) realizing (together with the server component) your intended use case. If Amazon stopped selling books and turned into a whether-info service instead, no amount of RPC-style API-level tight coupling would fix that and magically enforce your use case.

                  Jan
                • Paul Cohen
                  On Thu, Dec 22, 2011 at 8:45 AM, Jan Algermissen ... We can t. ... We have to do some work! ;-) ... Exactamente! Content negotiation is another underestimated
                  Message 8 of 20 , Dec 22, 2011
                    On Thu, Dec 22, 2011 at 8:45 AM, Jan Algermissen
                    <jan.algermissen@...> wrote:
                    > On Dec 22, 2011, at 7:50 AM, Jørn Wildt wrote:
                    >>  but I cannot see how
                    >> we can make clients for M2M interaction without hardwiring domain knowledge
                    >> into them?

                    We can't.

                    > Spot on :-) You must hard-wire domain knowledge into clients or communication won't happen. No matter how generic your media types is, you always end up putting in your code the knowledge about the domain.

                    We have to do some work! ;-)

                    >> As Paul states it "The web is not recompiled every morning - yet it works!".
                    >> Sure! But we do not recompile it because humans are so good at adopting to
                    >> whatever they see on a screen. But for a M2M system to work it surely must
                    >> be recompiled in order to understand new or changed semantics of the domain
                    >> it works with.
                    >
                    > No, this is not true thanks to content negotiation and well designed
                    > extension rules for payload formats.

                    Exactamente! Content negotiation is another underestimated and often
                    overlooked feature in REST/HTTP.

                    The robustness principle or Postel's law
                    (http://en.wikipedia.org/wiki/Postels_law) is fundamental to designing
                    and implementing good clients and servers:

                    Be liberal in what you accept, and conservative in what you send.

                    So assume as little as you can about the server in your design and
                    implementation of a client. And always assume the server will change.
                    Look on server data as duck-typed
                    (http://en.wikipedia.org/wiki/Duck_typing). If the data looks like
                    useful domain data you can assume it is.

                    We are talking about cross-enterprise system interfaces here. We can
                    not expect all enterprises to march in order with regards to system
                    releases and upgrades!

                    > The cases where a server needs to switch from application/procurement-v1 to
                    > application/procurement-v2 instantly, without a transition period of supporting
                    > those application/procurement-v1 enabled clients is extremely rare. (Feel free to
                    > construct an example).
                    >
                    > The cool thing about REST is that any form of evolution can take place without
                    > coordinating the change between clients, servers and intermediaries.

                    Not only cool. But to me this is the *core* business rationale for
                    chosing REST over RPC-style API:s for cross-enterprise system
                    interfaces.

                    > This is so natural to use Web users and I continue to find it astonishing that
                    > business systems owners are not jumping like mad on that feature regarding their
                    > internal IT systems.

                    I agree.

                    /Paul

                    --
                    Paul Cohen
                    www.seibostudios.se
                    mobile: +46 730 787 035
                    e-mail: paul.cohen@...
                  • Jan Algermissen
                    ... Understood - I did mean to add my 2 cents to the discussion, not to correct or argue with you. Sorry :-) ... Dunno. I *think* that Mike s and my thinking
                    Message 9 of 20 , Dec 22, 2011
                      On Dec 22, 2011, at 9:40 AM, Jorn Wildt wrote:

                      > > > Okay. That (and the rest you wrote) makes good sense. But I still feel sorry for the cats that get kicked when someone mints a new media type.
                      > >
                      > > Why?
                      >
                      > Not because I am going to kick them, I believe myself to be completely aligned with your opinion.

                      Understood - I did mean to add my 2 cents to the discussion, not to 'correct' or argue with you. Sorry :-)

                      > It's just that Mike and Eric's comment (http://tech.groups.yahoo.com/group/rest-discuss/message/18127), about kicking a cat every time a new media type is minted, is contrary to your view on media types. They may although be referring to different scenarios?

                      Dunno. I *think* that Mike's and my thinking is rather aligned and that Eric is a tiny bit more in favor of doing stuff with link rels than suitable for my personal taste. (Just my impression over the years)

                      I usually favor real ('big') media types over what I would consider link relation bloat :-) because it can help to capture protocol semantics in a single document. I also like it when clients constitute an implementation of 'one big' thing as opposed to being a generic machine with link-rel plugins lumped into them.

                      However, design decisions depend on the actual case and I have done both with satisfaction. What it comes down to is, I guess, the idea that not every service should lead to a new media type. You should investigate your anticipated canonical use cases (the ones that inspire and drive your media type design in the first place) to find similar protocol aspects and then stuff those into 1-N media types - with N being not too large (hah! great advice :-)

                      Jan


                      >
                      > > And sure, in m2m contexts, you have to take care not to suffer media type bloat. OTH, the latter will be much better than XML schema and RPC-API bloat.
                      >
                      > Yes, having a (enterprise) central definition of a quote representation must be way better than ten different departments having each their own SOAP/schema for that.
                      >
                      > Thanks, Jørn
                      >
                      >
                    • Jorn Wildt
                      ... I am not sure I understand this part. What does an XML schema mean to you? I completely agree on not needing a placeOrder()
                      Message 10 of 20 , Dec 22, 2011
                        > This is why you do not need an <order-placement-request> XML schema (or a placeOrder() method for that matter) - it is sufficient, for example, to base the actual communication on a domain-independent media type spec such as AtomPub and POST <order>s to an AtomPub server *that whoever configures the application knows to be an order-processing-service*.

                        I am not sure I understand this part. What does "an <order-placement-request> XML schema" mean to you?

                        I completely agree on not needing a placeOrder() method - doing a POST <order> to an appropriate collection is enough. But I don't see why using AtomPub makes any change? I still have to POST a domain specific media type <order>? So having a generic media type like AtomPub doesn't remove the need for domain specific stuff?

                        /Jørn
                      • Jan Algermissen
                          ... I meant, that the specific intent ( I send you this and request specifically that you process it as an order ) need not be part of the hypermedia. It is
                        Message 11 of 20 , Dec 22, 2011

                           


                          Jorn Wildt <jw@...> hat am 22. Dezember 2011 um 10:44 geschrieben:

                          > > This is why you do not need an <order-placement-request> XML schema (or a placeOrder() method for that matter) - it is sufficient, for example, to base the actual communication on a domain-independent media type spec such as AtomPub and POST <order>s to an AtomPub server *that whoever configures the application knows to be an order-processing-service*.
                          >
                          > I am not sure I understand this part. What does "an <order-placement-request> XML schema" mean to you?

                           

                          I meant, that the specific intent ("I send you this and request specifically that you process it as an order") need not be part of the hypermedia. It is already part of the act of picking *that* service.

                           

                          >
                          > I completely agree on not needing a placeOrder() method - doing a POST <order> to an appropriate collection is enough. But I don't see why using AtomPub makes any change? I still have to POST a domain specific media type <order>? So having a generic media type like AtomPub doesn't remove the need for domain specific stuff?

                           

                          Yes, it does not remove the need to speak the same language. If you need to transfer information, the receiver needs to be able to understand the structure of the data. here '<order .../>'. What I tried to point out is that the order is orthogonal to the interaction intent. <order> will work in many other places, too. It need not be owned by the service.

                           

                           

                          The specific coupling happens around the intent - and will regardless of protocol style. Nothing in an RPC API call such as getPendingOrders() guarantees that the service will actually put all the pending orders in the reply. That is the client's intent and it is 'backed up' by the choice of a specific service rather than a guarantee of the API spec.

                           

                          Jan

                           

                           

                           

                          >
                          > /Jørn
                          >
                        • Jorn Wildt
                          ... Ah! Thanks. Yes, by picking a specific URL (service) there is no need for further telling of the intention. The location/URL/service ~/orders plus the
                          Message 12 of 20 , Dec 22, 2011
                            > I meant, that the specific intent ("I send you this and request specifically
                            > that you process it as an order") need not be part of the hypermedia. It is
                            > already part of the act of picking *that* service.

                            Ah! Thanks. Yes, by picking a specific URL (service) there is no need for further telling of the intention. The location/URL/service ~/orders plus the operation POST <order> becomes the operation "add-to-orders".

                            Thanks for clarifying.

                            > <order> will work in many other places

                            Yes, that's a nice feature.

                            BTW: based on this discussion (among other things) we decided to go with a REST API on the current project :-) Thanks a lot for the input.

                            /Jørn
                          • Eric J. Bowman
                            ... Don t know how you got that impression; every time a new link relation is minted to express semantics already standardized in generic media types, a cat
                            Message 13 of 20 , Dec 22, 2011
                              Jan Algermissen <jan.algermissen@...> wrote:
                              >
                              > > It's just that Mike and Eric's comment
                              > > (http://tech.groups.yahoo.com/group/rest-discuss/message/18127),
                              > > about kicking a cat every time a new media type is minted, is
                              > > contrary to your view on media types. They may although be
                              > > referring to different scenarios?
                              >
                              > Dunno. I *think* that Mike's and my thinking is rather aligned and
                              > that Eric is a tiny bit more in favor of doing stuff with link rels
                              > than suitable for my personal taste. (Just my impression over the
                              > years)
                              >

                              Don't know how you got that impression; every time a new link relation
                              is minted to express semantics already standardized in generic media
                              types, a cat gets its tail stepped on. I've pushed back against "magic"
                              link relations plenty. Don't worry about my cat, he's 19 and quite used
                              to all the abuse...

                              A proper nutshell summary of me, is that Atom / HTML+RDFa provide
                              sufficient semantics for most any generic object interface. I have yet
                              to create a media type, and object strongly to the notion that REST
                              developers should mint new media types for every project.

                              When Roy says, "A REST API should spend almost all of its descriptive
                              effort in defining the media type(s) used for representing resources
                              and driving application state" I interpret that to mean something like,
                              "HTML <object> syntax is used to communicate URI templates" suffices as
                              documentation. Not, "a new media type has been created to drive
                              application state using URI templates."

                              -Eric
                            • Erik Wilde
                              hello eric. ... if you use RDFa, you introduce another vocabulary through the back door. that s fine with me, i just want to point out that this is no
                              Message 14 of 20 , Dec 22, 2011
                                hello eric.

                                > A proper nutshell summary of me, is that Atom / HTML+RDFa provide
                                > sufficient semantics for most any generic object interface. I have yet
                                > to create a media type, and object strongly to the notion that REST
                                > developers should mint new media types for every project.

                                if you use RDFa, you introduce another vocabulary through the back door.
                                that's fine with me, i just want to point out that this is no different
                                from using XML and application/xml as media type and then depend on
                                applications understanding the schema being used by picking up hints
                                such as DOCTYPE or namespaces or xsi:schemaLocation. if you have
                                specific application domain concepts that must be understood by clients
                                to engage in meaningful interaction patterns, then there are only
                                variations of how to push this complexity somewhere. the magic of HTML
                                is that the interaction semantics are application-agnostic, and the same
                                is true for Atom, but for any application that cannot depend on an
                                intelligent person driving the client through every single interaction,
                                you need more semantics to make things work.

                                personally (just like you, i think), i am in favor of using fewer media
                                types and having vocabularies in there which must be understood by
                                clients to continue their path, but i do have certain sympathy for the
                                argument that exposing this vocabulary in a visible way on the protocol
                                level has some advantages, too.

                                cheers,

                                dret,
                              • Mike Kelly
                                ... The problem with both Atom and RDF(a) is that they have significant baggage and aren t particularly simple. I think at large part of the reason the generic
                                Message 15 of 20 , Dec 22, 2011
                                  On Thu, Dec 22, 2011 at 8:11 PM, Eric J. Bowman <eric@...> wrote:
                                  > A proper nutshell summary of me, is that Atom / HTML+RDFa provide
                                  > sufficient semantics for most any generic object interface.  I have yet
                                  > to create a media type, and object strongly to the notion that REST
                                  > developers should mint new media types for every project.


                                  The problem with both Atom and RDF(a) is that they have significant
                                  baggage and aren't particularly simple. I think at large part of the
                                  reason the generic media type approach had not been adopted more
                                  widely is due to this.

                                  Hopefully HAL will change this trend since it's designed with REST and
                                  simplicity in mind - we've had good feedback and adoption seems to be
                                  growing. I'm surprised I haven't had more input from folks such as
                                  yourself Eric as I think your input and support would be valuable at
                                  this relatively early stage.

                                  Cheers,
                                  Mike
                                • Eric J. Bowman
                                  ... REST is not about distributed objects, it s about distributed object interfaces. Domain-specific vocabulary isn t exposed at the protocol layer, it s
                                  Message 16 of 20 , Dec 22, 2011
                                    "Jorn Wildt" wrote:
                                    >
                                    > I completely agree on not needing a placeOrder() method - doing a
                                    > POST <order> to an appropriate collection is enough. But I don't see
                                    > why using AtomPub makes any change? I still have to POST a domain
                                    > specific media type <order>? So having a generic media type like
                                    > AtomPub doesn't remove the need for domain specific stuff?
                                    >

                                    REST is not about distributed objects, it's about distributed object
                                    interfaces. Domain-specific vocabulary isn't exposed at the protocol
                                    layer, it's embedded within generic-media-type representations.

                                    Think of anything you've ever ordered online. The interface is HTML,
                                    not some domain-specific media type. Yet somehow this works. What
                                    you POST is really just some name-value pairs. HTML has loads of
                                    semantics for expressing name-value pairs.

                                    What HTML lacks is a way of expressing the meaning of a name. Which is
                                    where RDFa comes in. The GoodRelations ontology allows decoupled
                                    clients to determine that a name refers to a part #, and another name
                                    refers to the unit price, allowing an agent to comparison-shop between
                                    multiple services whose markup varies widely.

                                    -Eric
                                  • Jørn Wildt
                                    ... where RDFa comes in. And I cannot disagree with you. Yes, HTML + RDFa + POST can solve just about anything you throw at
                                    Message 17 of 20 , Dec 22, 2011
                                      Eric, we have had this discussion before:

                                      > What HTML lacks is a way of expressing the meaning of a name. Which is
                                      where RDFa comes in.

                                      And I cannot disagree with you. Yes, HTML + RDFa + POST
                                      <application/x-www-form-urlencoded> can solve just about anything you throw
                                      at it.

                                      > REST is not about distributed objects, it's about distributed object
                                      interfaces. Domain-specific vocabulary isn't exposed at the protocol
                                      layer, it's embedded within generic-media-type representations.

                                      So application/xml could be just as good as text/html since it doesn't
                                      expose the domain vocabulary at the protocol layer? Let me answer that
                                      question myself: yes, but there is something missing - in HTML you get
                                      hypermedia semantics (links, forms) for free whereas in XML you have to
                                      reinvent it for every vocabulary.

                                      So the dilema is: By leveraging HTML you get full hypermedia semantics but
                                      have to embed domain data in it using tricks like RDFa. On the other hand,
                                      by using plain XML you have a straight forward way to encode domain data but
                                      have no predefined hypermedia semantics. Right?

                                      /Jørn

                                      ----- Original Message -----
                                      From: Eric J. Bowman
                                      To: Jorn Wildt
                                      Cc: rest-discuss@yahoogroups.com
                                      Sent: Thursday, December 22, 2011 10:23 PM
                                      Subject: Re: [rest-discuss] Re: REST is not about domain models



                                      "Jorn Wildt" wrote:
                                      >
                                      > I completely agree on not needing a placeOrder() method - doing a
                                      > POST <order> to an appropriate collection is enough. But I don't see
                                      > why using AtomPub makes any change? I still have to POST a domain
                                      > specific media type <order>? So having a generic media type like
                                      > AtomPub doesn't remove the need for domain specific stuff?
                                      >

                                      REST is not about distributed objects, it's about distributed object
                                      interfaces. Domain-specific vocabulary isn't exposed at the protocol
                                      layer, it's embedded within generic-media-type representations.

                                      Think of anything you've ever ordered online. The interface is HTML,
                                      not some domain-specific media type. Yet somehow this works. What
                                      you POST is really just some name-value pairs. HTML has loads of
                                      semantics for expressing name-value pairs.

                                      What HTML lacks is a way of expressing the meaning of a name. Which is
                                      where RDFa comes in. The GoodRelations ontology allows decoupled
                                      clients to determine that a name refers to a part #, and another name
                                      refers to the unit price, allowing an agent to comparison-shop between
                                      multiple services whose markup varies widely.

                                      -Eric
                                    • Eric J. Bowman
                                      ... Well, yeah, there s that. ... Me in a nutshell, is if an m2m process is dealing with data which amounts to a purchase order, why not make its interface
                                      Message 18 of 20 , Dec 22, 2011
                                        Jørn Wildt wrote:
                                        >
                                        > So application/xml could be just as good as text/html since it
                                        > doesn't expose the domain vocabulary at the protocol layer? Let me
                                        > answer that question myself: yes, but there is something missing - in
                                        > HTML you get hypermedia semantics (links, forms) for free whereas in
                                        > XML you have to reinvent it for every vocabulary.
                                        >

                                        Well, yeah, there's that.

                                        >
                                        > So the dilema is: By leveraging HTML you get full hypermedia
                                        > semantics but have to embed domain data in it using tricks like RDFa.
                                        > On the other hand, by using plain XML you have a straight forward way
                                        > to encode domain data but have no predefined hypermedia semantics.
                                        > Right?
                                        >

                                        Me in a nutshell, is if an m2m process is dealing with data which
                                        amounts to a purchase order, why not make its interface *look* like a
                                        purchase order? The extra overhead is rendered moot in REST if you're
                                        using compression, caching, and a progressively-renderable media type.
                                        Don't un-solve the problem of network latency when transferring data
                                        from point A to point B for the sake of saving a few bytes, it's a
                                        false economy with cumulative consequences over the long term.

                                        By my definition, hypertext semantics doesn't just apply to ‌linking and
                                        forms, but to semantic structure. IOW, hypertext includes not just
                                        making an abbreviation a link to a definition, but <abbr title=
                                        'etcetera'>etc.</abbr> as well. More importantly, various list markup
                                        for describing lists of whatever, plus table markup for describing
                                        tabular data; and the ability to nest these within one another, allows
                                        the structure of the object interface to convey the relationship between
                                        linked/embedded objects even if those objects have complex structures.

                                        What I'm saying is, the structure of a purchase-order object is tabular,
                                        so its interface may be modeled as a <table>. This <table> can be
                                        manipulated via XForms and PUT in whole, or the <table> can contain a
                                        <form> or two to POST partial data. Following the accessibility
                                        guidelines makes such documents both human and machine readable. In
                                        the m2m case, there's more work to do. If this work builds on human-
                                        readable code, there's no need to then go back and make an m2m format
                                        human-readable and accessible so it can be understood by those charged
                                        with maintaining or interoperating with it. Or worry about making it
                                        stream processable.

                                        I can infer the meaning of a purchase order presented as a table easily
                                        enough, column B x column C = column D while the sum of column D is the
                                        total cost. Describing this to a machine user is the challenge, but
                                        there's an ontology for that -- which applies to application/xml too.
                                        The difference is that the same data structure presented as semantic
                                        HTML is readily apparent to anyone who needs to understand that data
                                        structure (for interoperability or maintenance), plus its progressive
                                        rendering rules are well-known so it's stream processable. Not to
                                        mention browser-based test/debug.

                                        I don't have to learn some new, undocumented media type by reverse-
                                        engineering a system's functionality. In 20 years, if I'm reverse-
                                        engineering a system written in obscured code in a dead language, the
                                        job is much easier if I can understand the data format just by looking
                                        at it. HTML is a great language not just for presenting a purchase-
                                        order interface, but also for inlining the documentation for that
                                        interface within the data-exchange format. Interoperability is easier
                                        if external organizations don't even need to know about your internal
                                        objects; they're free to come up with their own provided they comply
                                        with your API. You get to change your objects that way, too. None of
                                        this is possible when data formats are object serializations rather
                                        than object interfaces.

                                        Hypertext also includes vector-based images, or in HTML the ability to
                                        embed an image, where the domain-specific definition of the image has a
                                        specific meaning (using a GIF as an array). Anyway, my point is that
                                        there's an awful lot of meaning which can be conveyed by the structure
                                        of the markup, instead of by overloading link relations or any RDF
                                        implementation (embedded/RDFa or linked, or microdata). Such meaning is
                                        standardized, how you're using it is what you document about your API.
                                        You can usually do this in-line, for human and machine users.

                                        HTML wrapped with Atom may be used to define most REST APIs I can think
                                        of, and if I go that route, many of the benefits of REST immediately
                                        accrue. Ubiquitous media types provide stream-processable, massively-
                                        cacheable, widely-interoperable, long-term-stable data modeling for
                                        object interfaces. Why _wouldn't_ I want all that, from the start,
                                        off-the-shelf, re-usable from one project to the next -- absolutely
                                        free? Creating new media types seems like work, I prefer to REST...

                                        -Eric
                                      • Jørn Wildt
                                        Eric, you certainly make a good case for HTML. The only problem I have with it is the development overhead needed for reading out semantic data in M2M
                                        Message 19 of 20 , Dec 22, 2011
                                          Eric, you certainly make a good case for HTML. The only problem I have with
                                          it is the development overhead needed for reading out semantic data in M2M
                                          scenarios. Why? Because there is no standard generic way of embedding
                                          machine readable data in HTML. Yes, it is possible to use tables and other
                                          markup elements as you describe. But you will have to handcraft the decoding
                                          on the client side for each and every resource type.

                                          > I don't have to learn some new, undocumented media type by reverse-
                                          engineering a system's functionality.

                                          This is where I do not agree. Yes, the media type is well known, but the
                                          embedding format is not. Now you need to reverse engineere how the domain
                                          data is embedded.

                                          I have the same problem with micro formats: they work nicely with HTML, but
                                          you have to write specialized encoders/decoders for each and every format
                                          out there.

                                          Compare this to a generic serialization format like XML or JSON where
                                          encoding and decoding comes for free for just about all object formats.

                                          RDFa could be a solution to this, but its triplet semantics requires some
                                          thinking out of the box for object encoding.

                                          And, yes, I am a big fan of tools that helps consumers of my API getting
                                          started without too much overhead. For instance by supplying an XML schema
                                          they can use to auto-generate code - the .NET XML serializer has no problem
                                          ignoring unknown elements so the server can evolve without breaking the
                                          client.

                                          Now, if it was possible to find a generic and standardized way of embedding
                                          machine readable data in HTML such that you could have generic serializers
                                          as if it was XML, then I would love to use it!

                                          /Jørn
                                        • Eric J. Bowman
                                          I had this queued up as a draft, posted when I saw your other thread. ... Well, yes, RDFa and microdata. ... Yes, with microformats, but the problem of needing
                                          Message 20 of 20 , Dec 27, 2011
                                            I had this queued up as a draft, posted when I saw your other thread.

                                            Jørn Wildt wrote:
                                            >
                                            > Eric, you certainly make a good case for HTML. The only problem I
                                            > have with it is the development overhead needed for reading out
                                            > semantic data in M2M scenarios. Why? Because there is no standard
                                            > generic way of embedding machine readable data in HTML.
                                            >

                                            Well, yes, RDFa and microdata.

                                            >
                                            > Yes, it is possible to use tables and other markup elements as you
                                            > describe. But you will have to handcraft the decoding on the client
                                            > side for each and every resource type.
                                            >

                                            Yes, with microformats, but the problem of needing a parser for every
                                            vocabulary is solved by RDFa, so I don't understand your reservations
                                            about it.

                                            >
                                            > > I don't have to learn some new, undocumented media type by reverse-
                                            > engineering a system's functionality.
                                            >
                                            > This is where I do not agree. Yes, the media type is well known, but
                                            > the embedding format is not. Now you need to reverse engineere how
                                            > the domain data is embedded.
                                            >
                                            > I have the same problem with micro formats: they work nicely with
                                            > HTML, but you have to write specialized encoders/decoders for each
                                            > and every format out there.
                                            >

                                            An RDFa parser can easily generate name-value pairs. How those are
                                            interpreted by your system is up to you.

                                            >
                                            > Compare this to a generic serialization format like XML or JSON where
                                            > encoding and decoding comes for free for just about all object
                                            > formats.
                                            >

                                            I don't want to. I don't consume RDFa as RDF, I read it with XPath. I
                                            even use RDFa attributes in my CSS to make it more maintainable, vs.
                                            making up @class / @id values for each project. What I'm trying to
                                            accomplish is making my hypertext accessible to others, including those
                                            who wish to consume it as RDF, even though that isn't how _I_ build
                                            systems. General-purpose language for exchanging object interfaces, is
                                            all I'm looking for.

                                            >
                                            > RDFa could be a solution to this, but its triplet semantics requires
                                            > some thinking out of the box for object encoding.
                                            >

                                            Which is why I keep saying we're not encoding objects in hypertext,
                                            we're using hypertext to provide a generic object interface. All RDFa
                                            is to me, is a way to annotate this interface; then I struggle with
                                            making it sensible to RDFa parsers and let anyone who wants to consume
                                            it worry about relating whatever my triplet semantics happen to be, back
                                            to the problem at hand. It isn't my starting point.

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