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

19245Re: [rest-discuss] API versioning

Expand Messages
  • Jørn Wildt
    Jan 8, 2013
    • 0 Attachment
      Hi Eric

      > REST has no notion of resource "type" let alone of exposing same on the
      wire, so I've never understood why this solution is so prevalent in REST
      discussions. Just media types, which are agnostic as to what "type" of
      resource is being represented (with rare exceptions as parameters).

      I remember your stance on this from previous discussions. And, yes, a "sales order" or what ever other "type" you need can certainly be represented as (X)HTML. Sure, I am in no way questioning that.

      My question is though - from where does the client get the information it needs to extract, say, the order sum, delivery address, order lines quantity and so on from the generic payload?

      Let me expand with an example:

      - A client of mine sends me a link to a sales order and I want to import that into my local ERP system.

      - If the sales order is only available in (X)HTML, JSON or similar generic media type, how would I then be able to understand the content in enough detail to import it?

      - If the sales order was available in ATOM, I could at least import it as a document having a title and some content. But, okay, you can do that with (X)HTML too - albeit not with JSON and XML.

      - If the sales order was available in an even more domain specific media type, I could do an even better import of data.

      - ... and so on for various levels of domain specific media types ...

      Having a domain specific media type does although not imply any specific "type" of the resource itself - it only says "this particular resource can (also) be represented as XXX" - where XXX is an official application specific media type, for instance vCard or vCal which would allow the client to derive contact and calendar information from a resource - without making *any* kind of assumption about the underlying "type" of the it.

      Actually, I would argue that a generic media type is more "typed" than a domain specific media type. Okay, that sounds like rubbish, I know - but let me explain:

      - as I stated above, a domain specific media type lets you derived useful information from a resource without making any assumptions about its underlying type.

      - whereas a generic media type forces the client to magically assume the resource has a specific type with specific properties you can extract from the generic payload.

      Well, that is my current view on this issue ... and I have been swinging back and forth between your viewpoint and the above viewpoint during the last couple of years :-) Still open for new inputs!

      Thanks, Jørn


      On Tue, Jan 8, 2013 at 6:57 AM, Eric J. Bowman <eric@...> wrote:
       

      Keith Hassen wrote:
      >
      > This seems to be a recommended practice that I've encountered in
      > reading about RESTful implementations.
      >

      Perfectly good HTTP API practice; REST, not so much. The point of
      media types is to provide loose coupling based on shared understanding
      of how the representation is to be decoded. Not tight coupling based
      on interpreting the content of the representation. I've never seen an
      order API that couldn't be represented as HTML; despite any number of
      variations on this theme (or versions within), the media type doesn't
      vary between more order APIs on the Web than I can count.

      REST has no notion of resource "type" let alone of exposing same on the
      wire, so I've never understood why this solution is so prevalent in REST
      discussions. Just media types, which are agnostic as to what "type" of
      resource is being represented (with rare exceptions as parameters).


      >
      > > Anything else is up to the user-agent to work out. This is actually
      > > easier for m2m than h2m; a v1 m2m client should already ignore any
      > > hypertext it doesn't understand, rolling out v2 can then re-use any
      > > non-deprecated bits of the API already present plus the new stuff,
      > > and ignore the deprecated stuff. Can't it?
      >
      > Not always, at least not in my experience. :) I have found that
      > while breaking changes don't happen often, they *do* happen. Add to
      > this the possibility of different types of API consumers that start
      > off implementing your APIs the same way, but slowly (or rapidly!)
      > diverge over time. In some cases new resources (and thus new URIs)
      > will suffice, but in other cases what we are doing is very
      > specifically *evolving* the resource representation to accommodate
      > new requirements.
      >

      Then design for graceful degradation (or progressive enhancement) using
      client-side feature detection. Just saying there's no need to swing
      the conneg hammer to turn this particular screw.

      -Eric


    • Show all 13 messages in this topic