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

Re: [service-orientated-architecture] Re: Anne on REST-*

Expand Messages
  • Steve Jones
    2009/10/30 Jan Algermissen ... So is that the agreed global approach in the whole REST community? Is it a best practice that is
    Message 1 of 53 , Oct 30, 2009
      2009/10/30 Jan Algermissen <algermissen1971@...>
      >
      >
      >
      > On Oct 30, 2009, at 12:18 PM, Steve Jones wrote:
      >
      > > 2009/10/29 Jan Algermissen <algermissen1971@...>
      > >>
      > >>
      > >>
      > >> Steve,
      > >>
      > >> On Oct 29, 2009, at 12:00 AM, Steve Jones wrote:
      > >>
      > >>>
      > >>>
      > >>> What is the standard way of formally documenting (i.e. not just word
      > >>> documents), in advance of an operational system, what schemas are
      > >>> valid for what operations and what returns will be expected.
      > >>
      > >> When I tell you in prose that there is an ordering service
      > >> at http://foo.com/services/ordering/orders and that it
      > >> accepts orders of the type application/vnd.order+xml (and
      > >> supposing application/vnd.order+xml is already a standard)
      > >
      > > Pretty big assumption there.
      >
      > Well, all it'd take right now would be to assign the UBL XML
      > namespaces a media type, that's all.
      > For exampe: application/procurement+xml


      So is that the agreed global approach in the whole REST community? Is
      it a best practice that is broadly adopted? Or is it just a good idea
      that other people would disagree with?

      "that's all" hides a lot of agreement that is required.

      >
      > >
      > >
      > >> then you'd pretty much know all you need to know (the return
      > >> codes etc. are all in the HTTP spec).
      > >
      > > Not quite. I don't know what the return types are (i.e. when I do a
      > > PUT what do I get back?, what happens when I do a POST? etc)
      >
      > You know all this from the HTTP specification. The trick is to expect
      > all possibilities because we do not want unnecessary client
      > assumptions to cause unnecessary coupling.

      Oh for pities sake. So what you are saying is that I should _spend
      money_ writing _very_ complex code to handle a huge number of
      potential variations rather than just agreeing in advance what the
      returns are. This "trick" isn't a trick at all, people often said
      that about message queues "we'll put everything that you can receive
      on Queue X, you just code for whatever could be sent" its a classic
      technical "flexibility" argument which doesn't match the business
      flexibility.

      Take shipping. If I send you a bunch of information to send stuff in
      a container then you'd better send me back a bill of lading if it
      succeeds or a really specific message saying why it has failed. I
      want to know that in advance so I can ensure that my supply chain is
      strong and flexible. For me flexibility is the ability to delegate
      the responsibility and to potentially use multiple suppliers if I
      negotiate the discount contracts with them. At the technical level I
      don't give a monkey's about all of the "flexibility" that I could
      theoretically get from coping with whatever you want to send me. I
      want to ship stuff in containers.

      "expect all possibilities" is effectively an NP complete problem.


      >
      > Also, when you POST, you know everything you need to know. First, you
      > picked the resource to POST to based on what you learned about the
      > resource from previous hypertext (e.g. you pick /orders because you
      > learned that /orders is where you send your orders (much like a named
      > channel). POST means (and allwas does) 'process this'. Submitting
      > order data to an order-accepting resource is not different from
      > calling submitOrder() on an order service object.

      Why wouldn't I have used PUT to submit my order? What was it that told
      me to use POST on the previous query? When I submit the order (as
      above) what do I receive back? "Anything" is not a sensible answer.

      >
      > It is an illusion that you have more precision when doing the latter.
      > In both cases you pick the recipient of the message based on knowing
      > its nature.

      I _know_ what is being returned and I _know_ the exact HTTP method
      (PUT v POST) that I should have used. I also _know_ the schema(s)
      that can be submitted to that endpoint in a standardised way rather
      than based on someone's personal best practice.

      >
      > Just that the former style yields better evolvability.

      Where? Yes having an NP complete programming environment does indeed
      give more flexibility, it has of course only one drawback. One
      approach appears to be significantly quicker to deliver first off as
      building that NP complete environment might take sometime.

      >
      > >
      > > Also if you tell me in prose then we don't have anything formal and
      > > technical so we are back in dead tree land. Working code over
      > > documentation leaps to mind.
      >
      > How is for example the Atom/AtomPub spec not formal enough?

      It _might_ be formal enough but its not _agreed_ by people broadly
      that this is the right way to do it. It is a practice that is applied
      differently in lots of places and not at all in others.

      My point is not that it isn't _possible_ to do this but that there is
      no _standard_ way of doing it. Lots of local optimisations isn't a
      good thing.


      Steve
      >
      > Jan
      >
      > >
      > >
      > >>
      > >> You'd know
      > >>
      > >> - what URL to use for your request:
      > >> http://foo.com/services/ordering/orders
      > >> - how the payload should look like
      > >> - what to expect (any HTTP return code, the 2xx indicating success)
      > >>
      > >> E.g.:
      > >>
      > >> POST /service/ordering/orders
      > >> Host: foo.org
      > >> Content-Type: application/vnd.order+xml
      > >>
      > >> <order>
      > >> <item>A..</item>
      > >> <item>B..</item>
      > >> <!-- more order stuff like billing address etc. See UBL order doc
      > >> for example -->
      > >> </order>
      > >>
      > >> What do you feel is missing in terms of descriptions?
      > >
      > > Well everyone agreeing on this as an approach. An agreed way of
      > > defining content-type extensions for a project, company, industry or
      > > globally. A repository approach for the publication of this
      > > information so people can discover it _before_ the service is built to
      > > enable them to mock the service and build their end of the application
      > > ahead of time.
      > >
      > > You _can_ describe this stuff of course. My point is that there is no
      > > consistency around this. Google do it one way, Yahoo do it another
      > > and everyone else seems to have their own special flavour.
      > >
      > > This is a problem if you want lots of groups to work together.
      > >
      > >>
      > >>>
      > >>> Saying "its dynamic at run-time" doesn't exactly help if you want to
      > >>> do a big programme with pieces communicating using REST.
      > >>
      > >> Of course there needs to be a shared understanding of the
      > >> possibilities the client should
      > >> plan for because in the machine-to-machine interactions we have no
      > >> human mind
      > >> as the ultimate problem solver but a system has more freedom to
      > >> evolve
      > >> if the clients
      > >> reduce the assumptions they make about the server to the absolute
      > >> minimum.
      > >
      > > Which adds to the complexity and cost without actually guarenteeing
      > > that it increases the flexibility. The absolute minimum is a zero
      > > state of assumptions and everything is therefore an NP complete
      > > problem... a bit of a challenge. Lots of organisations with very
      > > formalised contracts can have huge flexibility while still keeping
      > > exactly the same interface. Sometimes in technology we obsess about
      > > technical flexibility and miss business flexibility.
      > >
      > >>
      > >> 'The absolute minimum' being:
      > >> - understanding of the media types used (this can be an enterprise-
      > >> wide mandatory set)
      > >
      > > Which is documented how?
      > >
      > >> - understanding of the complete HTTP redirection features (e.g. in
      > >> the
      > >> case of 201, 202
      > >> and 303)
      > >
      > > What is the HTTP return code for customer has failed anti money
      > > laundering validation due to not supplying a primary address which
      > > isn't a PO box?
      > >
      > >
      > >> - the order or at least dependency of certain goals (obviously I
      > >> cannot initiate a
      > >> shipment before there is an order) because there is just no way to
      > >> make this dynamic;
      > >> it is inherent in the collaboration client and server engage in
      > >> (e.g. ordering).
      > >
      > > Indeed, again how is this documented? Clearly with things like BPMN
      > > or BPEL you can do that. What is the REST approach? You could do
      > > this using formal contracts (which WS-* doesn't have) which would be
      > > better... but there isn't a REST approach for this yet.
      > >>
      > >> I do not see how formal descriptions (what would they look like
      > >> anyway?) would be
      > >> an improvement of any kind.
      > >
      > > So lets take a WS-* view from a technical perspective. I can publish
      > > a WSDL which includes the capabilities and says both the inbound and
      > > outbound schemas, I can publish a BPEL which says the ordering via
      > > which things must be called, and which can be used by consumers to
      > > ensure that.
      > >
      > > So in other words I have formal IT contracts against which I can run
      > > automated validation suites to ensure that both the consumers and
      > > producers are meeting the contracts and specifications I've laid down
      > > and none of this requires someone to interpret, potentially
      > > inaccurately, a word document or web page.
      > >
      > > Working code over dead tree documents
      > >
      > >>
      > >> Or am I misunderstanding you?
      > >
      > > Possibly.
      > >
      > > Steve
      > >>
      > >> Jan
      > >>
      > >>>
      > >>> Steve
      > >>>
      > >>>
      > >>> 2009/10/29 Jan Algermissen <algermissen1971@...>
      > >>>
      > >>> Steve,
      > >>>
      > >>>
      > >>>
      > >>> On Oct 28, 2009, at 12:55 AM, Steve Jones wrote:
      > >>>
      > >>>>
      > >>>>
      > >>>> Advice is great... but we need something a bit more formal for
      > >>>> organisations to adopt it as a long term strategy.
      > >>>
      > >>> Sorry, I did not follow this list recently. What does 'it' refer to?
      > >>> IOW, what is it for whoch adoption something more formal is needed?
      > >>>
      > >>> Thanks,
      > >>>
      > >>> Jan
      > >>>
      > >>>
      > >>>>
      > >>>> Steve
      > >>>>
      > >>>> 2009/10/28 Colin <colin.jack@...>
      > >>>>
      > >>>>
      > >>>>> And the question is what is the standard documentation format for
      > >>>> those
      > >>>>> mechanics?
      > >>>>
      > >>>> Ian Robinson posted some good advice on the REST-discuss group
      > >>>> about
      > >>>> this a while back:
      > >>>>
      > >>>> http://tech.groups.yahoo.com/group/rest-discuss/message/13108
      > >>>>
      > >>>>
      > >>>>> So when I do "Get" what is the standard way that I am then told
      > >>> that
      > >>>>>
      > >>>>> PUT HTTP://www.example.com/fish takes the fish.xsd
      > >>>>> and
      > >>>>> POST HTTP://www.example.com/fish takes the newfish.xsd
      > >>>>
      > >>>> I personally think Ian has a good point about considering the
      > >>>> approach Atom/AtomPub take, you might also find Subbu's InfoQ
      > >>>> article useful:http://www.infoq.com/articles/subbu-allamaraju-rest
      > >>>>
      > >>>> As you say making this all dynamic is, at this stage, not realistic
      > >>>> and so documentation for clients to read is a requirement.
      > >>>>
      > >>>> Thanks,
      > >>>>
      > >>>> Colin Jack
      > >>>>
      > >>>>
      > >>>>
      > >>>>
      > >>>>
      > >>>
      > >>> --------------------------------------
      > >>> Jan Algermissen
      > >>>
      > >>> Mail: algermissen@...
      > >>> Blog: http://algermissen.blogspot.com/
      > >>> Home: http://www.jalgermissen.com
      > >>> --------------------------------------
      > >>>
      > >>>
      > >>>
      > >>>
      > >>>
      > >>
      > >> --------------------------------------
      > >> Jan Algermissen
      > >>
      > >> Mail: algermissen@...
      > >> Blog: http://algermissen.blogspot.com/
      > >> Home: http://www.jalgermissen.com
      > >> --------------------------------------
      > >>
      > >>
      > >
      > >
      > > ------------------------------------
      > >
      > > Yahoo! Groups Links
      > >
      > >
      > >
      >
      > --------------------------------------
      > Jan Algermissen
      >
      > Mail: algermissen@...
      > Blog: http://algermissen.blogspot.com/
      > Home: http://www.jalgermissen.com
      > --------------------------------------
      >
      >
    • Michael Poulin
      Agree with Steve - Michael ________________________________ From: Steve Jones To: service-orientated-architecture@yahoogroups.com
      Message 53 of 53 , Nov 10, 2009
        Agree with Steve
        - Michael


        From: Steve Jones <jones.steveg@...>
        To: service-orientated-architecture@yahoogroups.com
        Sent: Mon, November 9, 2009 6:56:28 AM
        Subject: Re: [service-orientated-architecture] Re: Anne on REST-*

        2009/11/8 Jan Algermissen <algermissen1971@...>
        >
        >
        >
        > Steve,
        >
        > On Nov 8, 2009, at 1:05 PM, Steve Jones wrote:
        >
        > > This is the bit that surprises me about REST advocates. On the one
        > > hand they champion an extremely rigid and limited interface as being
        > > the right way to do things and in the same breath claim that rigid
        > > interfaces are a bad thing.
        >
        > I made a mistake in terminology there 'rigid' should have been
        > 'specific'.
        >
        > So, REST advocates prefer the uniform interface over the specific
        > because the
        > uniform interface has advantages over the specific[1]

        A claim without much evidence.  I'd argue that my claim that specific
        interfaces with tight definitions have significant advantages over
        undocumented dynamic interfaces.  802.11x, HTTP, GSM, etc, etc, etc

        Steve


        >
        > Sorry for the confusion.
        >
        > Jan
        >
        > [1] <http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5
        > >
        >
        > --------------------------------------
        > Jan Algermissen
        >
        > Mail: algermissen@...
        > Blog: http://algermissen.blogspot.com/
        > Home: http://www.jalgermissen.com
        > --------------------------------------
        >
        >


        ------------------------------------

        Yahoo! Groups Links

        <*> To visit your group on the web, go to:
            http://groups.yahoo.com/group/service-orientated-architecture/

        <*> Your email settings:
            Individual Email | Traditional

        <*> To change settings online go to:
            http://groups.yahoo.com/group/service-orientated-architecture/join
            (Yahoo! ID required)

        <*> To change settings via email:
            service-orientated-architecture-digest@yahoogroups.com
            service-orientated-architecture-fullfeatured@yahoogroups.com

        <*> To unsubscribe from this group, send an email to:
            service-orientated-architecture-unsubscribe@yahoogroups.com

        <*> Your use of Yahoo! Groups is subject to:
            http://docs.yahoo.com/info/terms/


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