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

Re: [rest-discuss] How much REST should your Web API get?

Expand Messages
  • Jørn Wildt
    ... Sorry, I was too quick here. The REST service is actually composed of two different sets of resources that mixes various parts of the system. Half of it is
    Message 1 of 46 , May 4, 2013
    • 0 Attachment
      > We have a custom media type "application/vendor.cbrain.casefiole+xml"

      Sorry, I was too quick here. The REST service is actually composed of two different sets of resources that mixes various parts of the system. Half of it is in "application/json" (the mobile part) - and half of it is in "application/vendor.cbrain.casefiole+xml" (the part designed for systems integration with third party vendors).

      As I said: I have yet to make up my mind w.r.t. custom versus generic media types.

      /Jørn


      On Sat, May 4, 2013 at 8:28 AM, Jørn Wildt <jw@...> wrote:
      Regarding "service document": what if I called it "home page" or "home document" - would it make a difference? The problem with the classic "service document" is that it, in the SOAP world, includes type information and is meant for static "development time" binding. That is not the case here: our "home document" only includes links with link-rels and a short description.

      Speaking about shared types ... Jimmy Bogard has a fresh blog post on this issue: http://lostechies.com/jimmybogard/2013/05/01/messages-data-and-types/

      The home document can be served as either one large JSON object with keys as link-rels and values as URLs (like HAL does it), HTML with <a href="..." rel="..."> or a homegrown XML format. Today I would probably have chosen something like JSON-home (http://tools.ietf.org/html/draft-nottingham-json-home-02), HAL or another hyper media enabled standard JSON media type.

      So, no, I do not think using a service document / home page disqualifies the service as being RESTful - as long as it is used for late binding at runtime (something which we make quite explicit in the documentation).

      > albeit probably at the cost of a lot of initial tooling

      Well, yes, some, but any client that understands JSON can do hyper media with something like HAL. The server is based on OpenRasta which also has nice support for creating links.


      > Also, just curious, are you using your own custom media type or just JSON/XML/other,

      We have a custom media type "application/vendor.cbrain.casefiole+xml". I still have to decide whether I prefer generic media types over custom media types - in this case we chose a custom media type to get some experience. I will write a piece on that later - when I have made up my mind about what I think about it.


      > The one thing I still have not been able to fully understand from Roy's rant was just exactly what he meant means by a "typed" resource?

      Yes, I have also had problems with that :-) But take my example from the previous post: the client and server does NOT share any kind of internal type knowledge about what is behind that resource - actually that would be a hopeless feat because the code base behind it is rather convoluted. What they share is an understanding of the message format - the public-stable-well defined-optimized for easy understanding by third party devs-format. When we change the actual implementation type behind the resource we do not change the external format. So servers and clients share message format - not implementation type - and the clients and servers are free to choose what ever internal types they want for representing it.

      In the case of <img> resources: the shared message contract is the jpg/gif/... format (media type). There is no shared understanding of the server side data/type from which the image was created.

      This mail was written with a 1 year old kid on my arm, so sorry for misspellings ... I have to leave now :-)

      Regards,, Jørn



      On Fri, May 3, 2013 at 11:41 PM, Mike Schinkel <mike@...> wrote:
      On May 3, 2013, at 3:57 PM, Jørn Wildt <jw@...> wrote:
      We decided to go "full monty" and stick as closely as possible to the REST constraints - especially hyper media. This means our clients have one, and only one, single entry point to the REST service - and that entry point contains a service document with links/link-rels to all top level resources. 

      ...

      This too was easy using hyper media...

      The last happy moment also illustrates what (I think) was meant by "A REST API should never have “typed” resources that are significant to the client" in Roy's famous rant "REST APIs must be hypertext-driven". Had the client known anything about the internal type behind the facade then it would have failed when we introduced multiple types behind the facade.

      Not to diminish what you've accomplished, because it sounds like it works extremely well in practice albeit probably at the cost of a lot of initial tooling but I would question if the use of a "service document" does not by-definition disqualify it as being RESTful as per Roy's precise definition, ironically stated in the blog post rant you reference.

      As I understand it from a recent multiple re-reading of Roy's infamous rant the use of a service document would mean individual messages are indeed not fully description and that would disqualify it as being "RESTful."  Not that I disagree with the concept of a lightweight JSON-based service document that simply points out all the URLs; frankly I rather like the idea. But unless I mis-read or Roy has revised his definition of REST since that post I think service documents do not a RESTful web service make?

      Also, just curious, are you using your own custom media type or just JSON/XML/other, and if not the former does that also not disqualify it from being considered RESTful?  If you are using your own custom media type I'd be curious what the media type is, i.e. what is "xxxx-yyyy" for "application/"xxxx-yyyy" and what it's base format is; XML, JSON, HAL, ATOM, etc?

      The one thing I still have not been able to fully understand from Roy's rant was just exactly what he meant means by a "typed" resource?  Doesn't a <img> tag imply a resource of type JPEG, GIF or PNG, for example?  So I have never been fully able to grok that part.  Any clarifications from anyone?

      -Mike


    • Mike Schinkel
      Once again you have given me much to ponder. Thanks for the effort; I will be trying to internalize this. -Mike
      Message 46 of 46 , May 4, 2013
      • 0 Attachment
        Once again you have given me much to ponder. Thanks for the effort; I will be trying to internalize this.

        -Mike

        On May 4, 2013, at 1:49 PM, "Markus Lanthaler" <markus.lanthaler@...> wrote:

        > On Saturday, May 04, 2013 7:03 PM, Mike Schinkel wrote:
        >> Hmm. Okay, the more I think I understand about REST the more I think
        >> I don't understand and/or am unsure who actually really understands
        >> REST besides Roy.
        >>
        >> As I've read Roy I've come away understanding that messages must be
        >> self-contained
        >
        > No, you are confusing self-contained with self-descriptive.
        >
        >
        >> and the only thing the client should know is how the
        >> links in the returned representation are defined to behave as defined
        >> by the representation's content yype. Having links in one document and
        >> data in a second document where you have to have the contents of both
        >> documents seems to me to violate that need for self-containment.
        >
        > ... if there would be a self-containment constraint that would be true --
        > but there isn't.
        >
        >
        >> I do have one question; if there is a home document that is cacheable
        >> for some period "X" and at the time immediately after an API client
        >> retrieves the home document the servers are moved and the client later
        >> perform an operation that requires URLs from the home document but
        >> before "X" time has passed, it can cause failure. If the message is
        >> self-contained that time window is greatly reduced. This is one of the
        >> reasons I can postulate there is a need for self-contained messages.
        >
        > That doesn't matter at all. Program defensively, detect the error, and
        > recover.
        >
        > I could just as well argue that separating them allows you to request them
        > in parallel which would probably be faster so the time window you are
        > talking about would be reduced even further.
        >
        >
        >
        > --
        > Markus Lanthaler
        > @markuslanthaler
        >
      Your message has been successfully submitted and would be delivered to recipients shortly.