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

Related resource: Inlined or linked

Expand Messages
  • Vitaly Stakhov
    I think the first time I saw this pattern in Jon Moore s oredev talk on Hypermedia APIs. In his demo he replaced links to subresources with their full
    Message 1 of 3 , Mar 3, 2012
    • 0 Attachment
      I think the first time I saw this pattern in Jon Moore's oredev talk on Hypermedia APIs. In his demo he replaced links to subresources with their full representations and the client continued to work. 

      Mike Amundsen in his hypermedia book talks about this approach as well. Specifically:

      "The code above assumes that a call to the initial UI will always return a representation that contains the Collection+JSON template object. While this is true for the implementation we are testing, that might not be true for all servers. It is possible that servers will send only a link to the template object..."

      The part of documentation of the media type regarding the relation of the resource containing the template and the template itself: 

      "The collection object MAY have a template object child property".

      Note, nothing is mentioned about either template object is linked or inlined. I assume it should be always inlined otherwise it's not clear what the name of the link rel should be.

      And then goes on with:

      "It is important to review the semantic requirements fo the target media type carefully in order to account for any possible variances in the way representations may be presented by compliant servers. Never assume all servers will implement the media type the same way."

      It sounds like the related resource may be either linked or inlined - whatever the server decides. I can understand the approach if the media type explicitly says that there should be either a link OR an inlined resource. But when it says there should be an inlined resource and the server decides to return a link to it, then the server is not implementing the media type anymore. And vice versa, when media type says there should be a link, but the server returns an inline target resource.

      So my question is rather broad, but please feel free to express any of your thoughts on the topic: in which cases servers may decide to either go with inlined or linked resource and clients should be expecting that possible move from the servers?

      --
      Cheers,
      Vitaly

    • Erlend Hamnaberg
      ... Hi Vitaly. In Atom it would be quite useful to have a summary representation in a feed that represents a search result, but allow the full representation
      Message 2 of 3 , Mar 4, 2012
      • 0 Attachment
        On Sat, Mar 3, 2012 at 2:57 PM, Vitaly Stakhov <vitaly.st@...> wrote:
         

        I think the first time I saw this pattern in Jon Moore's oredev talk on Hypermedia APIs. In his demo he replaced links to subresources with their full representations and the client continued to work. 


        Mike Amundsen in his hypermedia book talks about this approach as well. Specifically:

        "The code above assumes that a call to the initial UI will always return a representation that contains the Collection+JSON template object. While this is true for the implementation we are testing, that might not be true for all servers. It is possible that servers will send only a link to the template object..."

        The part of documentation of the media type regarding the relation of the resource containing the template and the template itself: 

        "The collection object MAY have a template object child property".

        Note, nothing is mentioned about either template object is linked or inlined. I assume it should be always inlined otherwise it's not clear what the name of the link rel should be.

        And then goes on with:

        "It is important to review the semantic requirements fo the target media type carefully in order to account for any possible variances in the way representations may be presented by compliant servers. Never assume all servers will implement the media type the same way."

        It sounds like the related resource may be either linked or inlined - whatever the server decides. I can understand the approach if the media type explicitly says that there should be either a link OR an inlined resource. But when it says there should be an inlined resource and the server decides to return a link to it, then the server is not implementing the media type anymore. And vice versa, when media type says there should be a link, but the server returns an inline target resource.

        So my question is rather broad, but please feel free to express any of your thoughts on the topic: in which cases servers may decide to either go with inlined or linked resource and clients should be expecting that possible move from the servers?

        --
        Cheers,
        Vitaly

        Hi Vitaly.

        In Atom it would be quite useful to have a summary representation in a feed that represents a search result, but allow the full representation in a "content-listing" resource. The summary would obviously link to the full representation.

        Switching to the full representation in a search result would also be possible, but would need a separate URI, meaning a different resource.

        --
        Erlend
      • Moore, Jonathan (CIM)
        You are correct that the media type definition has to allow for this degree of freedom or the server can t exercise it without potentially breaking compliant
        Message 3 of 3 , Mar 5, 2012
        • 0 Attachment
          You are correct that the media type definition has to allow for this degree of freedom or the server can't exercise it without potentially breaking compliant clients.

          HTML5 microdata such as that described on http://schema.org/ would be an example media type; if an @itemprop is on an <a> tag, that's a pretty good indication that value is remote vs. inline; e.g.

          <div itemscope itemtype="http://schema.org/Restaurant">
            <a itemprop="address" href="…"/> <!-- linked/remote postal address -->
          </div>

          Or:

          <div itemscope itemtype="http://schema.org/Restaurant">
            <div itemprop="address" itemtype="http://schema.org/PostalAddress">
              <!-- inlined postal address -->
             …
            </div>
          </div>

          Jon

          From: Vitaly Stakhov <vitaly.st@...>
          Date: Sat, 3 Mar 2012 15:57:38 +0200
          To: <rest-discuss@yahoogroups.com>
          Subject: [rest-discuss] Related resource: Inlined or linked

           

          I think the first time I saw this pattern in Jon Moore's oredev talk on Hypermedia APIs. In his demo he replaced links to subresources with their full representations and the client continued to work. 


          Mike Amundsen in his hypermedia book talks about this approach as well. Specifically:

          "The code above assumes that a call to the initial UI will always return a representation that contains the Collection+JSON template object. While this is true for the implementation we are testing, that might not be true for all servers. It is possible that servers will send only a link to the template object..."

          The part of documentation of the media type regarding the relation of the resource containing the template and the template itself: 

          "The collection object MAY have a template object child property".

          Note, nothing is mentioned about either template object is linked or inlined. I assume it should be always inlined otherwise it's not clear what the name of the link rel should be.

          And then goes on with:

          "It is important to review the semantic requirements fo the target media type carefully in order to account for any possible variances in the way representations may be presented by compliant servers. Never assume all servers will implement the media type the same way."

          It sounds like the related resource may be either linked or inlined - whatever the server decides. I can understand the approach if the media type explicitly says that there should be either a link OR an inlined resource. But when it says there should be an inlined resource and the server decides to return a link to it, then the server is not implementing the media type anymore. And vice versa, when media type says there should be a link, but the server returns an inline target resource.

          So my question is rather broad, but please feel free to express any of your thoughts on the topic: in which cases servers may decide to either go with inlined or linked resource and clients should be expecting that possible move from the servers?

          --
          Cheers,
          Vitaly

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