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

Content types and links

Expand Messages
  • Greg Young
    Let s imagine I had atompub with multiple serialization formats. If you asked my collection with Header: JSON and I gave you something like: { title :
    Message 1 of 8 , Sep 6, 2012
    • 0 Attachment
      Let's imagine I had atompub with multiple serialization formats. If
      you asked my collection with Header: JSON and I gave you something
      like:

      {
      "title": "vvvvvv",
      "id": "http://127.0.0.1:2113/streams/y/1",
      "updated": "2012-09-06T16:39:44.695643Z",
      "author": {
      "name": "ASDASDASD"
      },
      "summary": "Entry #1",
      "links": [
      {
      "uri": "http://127.0.0.1:2113/x/y/1",
      "relation": "edit"
      },
      {
      "uri": "http://127.0.0.1:2113/x/y/c/1?format=text",
      "type": "text/plain"
      },
      {
      "uri": "http://127.0.0.1:2113/x/y/c/1?format=json",
      "relation": "alternate",
      "type": "application/json"
      },
      {
      "uri": "http://127.0.0.1:2113/x/y/c/1?format=xml",
      "relation": "alternate",
      "type": "text/xml"
      }
      ]
      }

      Would it seem off to you that I gave you the alternates?


      --
      Le doute n'est pas une condition agréable, mais la certitude est absurde.
    • Eric J. Bowman
      ... I assume you mean Accept: application/json , which I d rather you would type than me... ... Conceptually, no, there s nothing wrong with including a list
      Message 2 of 8 , Sep 6, 2012
      • 0 Attachment
        Greg Young wrote:
        >
        > Header: JSON
        >

        I assume you mean "Accept: application/json", which I'd rather you
        would type than me...

        >
        > Would it seem off to you that I gave you the alternates?
        >

        Conceptually, no, there's nothing wrong with including a list of
        alternates using rel='alternate' in any media type which implements link
        relations. Which application/json doesn't, meaning your example doesn't
        implement REST. Sure, you can serialize Atom as JSON or XML, but the
        results aren't self-descriptive, which violates the uniform interface
        constraint.

        The fix is to define a JSON serialization of Atom and register
        application/atom+json for it; in the meantime, it's important to
        understand where your system deviates from REST's idealized model.
        It's become de rigeur to serialize Atom as JSON in this fashion, but it
        doesn't meet Roy's definition of visibility, because everyone does it a
        little bit differently while visibility is a product of standardization.

        All those similar efforts slap application/json on it, which is truly
        opaque because that media type doesn't define linking. Meaning the only
        way to deduce "hey, this is Atom" is by sniffing the content and making
        lots of assumptions about syntax. Standardization is required for this
        to become visible; even then, proliferation is required before REST's
        benefits would be fully realized.

        Using REST as an evaluation tool in this manner, presents you with two
        options: one, re-architect the system, if you need the full benefits of
        REST from the get-go; or two, wait for the Web to catch up, participate
        in the standardization process by writing an I-D for the Atom WG. I'd
        suggest, if you have to build your system this way, using a media type
        of application/x.atom+json until such time as standardization occurs.

        -Eric
      • Greg Young
        Actually I meant to type Accept :) I was reading/typing two things at once. Likely header came in because I was reading headers from curl ... We have sat on
        Message 3 of 8 , Sep 6, 2012
        • 0 Attachment
          Actually I meant to type Accept :) I was reading/typing two things at
          once. Likely header came in because I was reading "headers" from curl
          :)

          We have sat on the fence for a while about how to handle content type
          here as there is no 'good' answer. If I do as x. I break tools. If I
          don't I break "rest". I have still not made a decision on how to
          handle this.

          The interesting bit to me was if I am in that format (and we assume
          you are coming to me to read a feed) do the others have value?

          Greg

          On Thu, Sep 6, 2012 at 3:44 PM, Eric J. Bowman <eric@...> wrote:
          > Greg Young wrote:
          >>
          >> Header: JSON
          >>
          >
          > I assume you mean "Accept: application/json", which I'd rather you
          > would type than me...
          >
          >>
          >> Would it seem off to you that I gave you the alternates?
          >>
          >
          > Conceptually, no, there's nothing wrong with including a list of
          > alternates using rel='alternate' in any media type which implements link
          > relations. Which application/json doesn't, meaning your example doesn't
          > implement REST. Sure, you can serialize Atom as JSON or XML, but the
          > results aren't self-descriptive, which violates the uniform interface
          > constraint.
          >
          > The fix is to define a JSON serialization of Atom and register
          > application/atom+json for it; in the meantime, it's important to
          > understand where your system deviates from REST's idealized model.
          > It's become de rigeur to serialize Atom as JSON in this fashion, but it
          > doesn't meet Roy's definition of visibility, because everyone does it a
          > little bit differently while visibility is a product of standardization.
          >
          > All those similar efforts slap application/json on it, which is truly
          > opaque because that media type doesn't define linking. Meaning the only
          > way to deduce "hey, this is Atom" is by sniffing the content and making
          > lots of assumptions about syntax. Standardization is required for this
          > to become visible; even then, proliferation is required before REST's
          > benefits would be fully realized.
          >
          > Using REST as an evaluation tool in this manner, presents you with two
          > options: one, re-architect the system, if you need the full benefits of
          > REST from the get-go; or two, wait for the Web to catch up, participate
          > in the standardization process by writing an I-D for the Atom WG. I'd
          > suggest, if you have to build your system this way, using a media type
          > of application/x.atom+json until such time as standardization occurs.
          >
          > -Eric



          --
          Le doute n'est pas une condition agréable, mais la certitude est absurde.
        • Eric J. Bowman
          ... Decide whatever you want, provided you understand the ramifications. Tools will eventually grok the +json media type suffix. REST is about long-term
          Message 4 of 8 , Sep 6, 2012
          • 0 Attachment
            Greg Young wrote:
            >
            > We have sat on the fence for a while about how to handle content type
            > here as there is no 'good' answer. If I do as x. I break tools. If I
            > don't I break "rest". I have still not made a decision on how to
            > handle this.
            >

            Decide whatever you want, provided you understand the ramifications.
            Tools will eventually grok the +json media type suffix. REST is about
            long-term design, there's nothing wrong with having to wait a few years
            for standardization to catch up. When it does you'll hopefully not have
            painted yourself into a legacy-support corner, by failing to anticipate
            change or planning how to accommodate it when it comes, in the design
            phase.

            >
            > The interesting bit to me was if I am in that format (and we assume
            > you are coming to me to read a feed) do the others have value?
            >

            I don't think there's much value to having multiple serializations,
            seems more like something folks do in order to check boxes for feature
            support, mostly. If you're running an origin server and offering a
            JSON serialization for Atom content, anyone building a client to consume
            that JSON will have their client break if/when you change syntax to
            support a standardized solution, due to tight coupling -- which isn't an
            issue when standard media types are adhered to.

            Whereas, if you only offer Atom, client developers can always add a
            layer (using, say, XSLT) which transforms your Atom into their desired
            JSON. If/when a standardized solution to that problem evolves, the
            client developer can decide whether or not to support it -- nothing
            breaks, so you're not in a position where you need to support legacy
            code by adding conneg on application/x.atom+json vs. application/atom+
            json, which increases the complexity of your system.

            I don't know your requirements, but I'd wait until the desired feature
            (Atom serialized as JSON) actually exists before implementing it, rather
            than trying to hit a moving target. Once application/atom+json is
            nailed down, it's easy enough to add in support to please client
            developers, without the extra complexity of supporting legacy code.
            Client developers can then remove their transformation layer, and change
            their Accept: header to request atom+json instead of atom+xml.

            In the meantime, there are benefits to be had from serving Atom as Atom,
            which are a long ways off for Atom serialized as JSON. Intermediaries
            aren't just caches, those with knowledge of Atom can prefetch DNS
            lookups, or atom:entry documents, or images etc. while third-party
            systems (i.e. Google) know how to handle (index, subscribe to) your
            data. As a REST true believer, I don't see the benefit of trading away
            this global, ubiquitous support of any system for the sake of easier
            development of tightly-coupled clients. Or, for byte shaving, which is
            a moot point when compression and caching are considered.

            http://tech.groups.yahoo.com/group/rest-discuss/message/8873

            Put another way, REST enables serendipitous re-use by all sorts of apps
            which have no knowledge of your system specifics. Why give that up to
            support the comparatively tiny number of applications developed
            specifically for your system? OK, sure, you can use conneg, but if the
            tiny number of purpose-built clients accounts for most of your users
            you're just shooting yourself in the foot -- their usage won't be
            accelerated via serendipitous re-use, and will degrade cache efficiency
            for any ubiquitous-media-type representations you're serving.

            I think when Roy says "engineer for serendipity" it applies to runtime,
            but is commonly misinterpreted to apply to design-time, which has led
            lots of folks to implement multiple serializations. I don't think Roy
            means "make it easier for third parties to write clients" so much as
            "support those clients already existing as part of the deployed
            infrastructure" because that's what allows a system to truly scale. By
            doing so, your system will automatically support any new clients added
            to the deployed infrastructure, which are based on the same standards
            you've adhered to. You don't need to know about them, and they don't
            need to know about you, which sounds pretty serendipitous to me.

            By clients, I mean both client connectors on intermediaries, and such
            things as googlebot. Target those by using ubiquitous media types which
            properly describe the linking/embedding semantics of your data.

            -Eric
          • Greg Young
            I don t know your requirements, but I d wait until the desired feature (Atom serialized as JSON) actually exists before implementing it, rather than trying to
            Message 5 of 8 , Sep 7, 2012
            • 0 Attachment
              "I don't know your requirements, but I'd wait until the desired feature
              (Atom serialized as JSON) actually exists before implementing it, rather
              than trying to hit a moving target. Once application/atom+json is
              nailed down, it's easy enough to add in support to please client
              developers, without the extra complexity of supporting legacy code.
              Client developers can then remove their transformation layer, and change
              their Accept: header to request atom+json instead of atom+xml."

              This is essentially what we do internally to support it. Default is normal atom.

              There are of course trade offs. I like the x.json to at least make it
              explicit what they are risking if they decide to use it.

              On Thu, Sep 6, 2012 at 8:52 PM, Eric J. Bowman <eric@...> wrote:
              > Greg Young wrote:
              >>
              >> We have sat on the fence for a while about how to handle content type
              >> here as there is no 'good' answer. If I do as x. I break tools. If I
              >> don't I break "rest". I have still not made a decision on how to
              >> handle this.
              >>
              >
              > Decide whatever you want, provided you understand the ramifications.
              > Tools will eventually grok the +json media type suffix. REST is about
              > long-term design, there's nothing wrong with having to wait a few years
              > for standardization to catch up. When it does you'll hopefully not have
              > painted yourself into a legacy-support corner, by failing to anticipate
              > change or planning how to accommodate it when it comes, in the design
              > phase.
              >
              >>
              >> The interesting bit to me was if I am in that format (and we assume
              >> you are coming to me to read a feed) do the others have value?
              >>
              >
              > I don't think there's much value to having multiple serializations,
              > seems more like something folks do in order to check boxes for feature
              > support, mostly. If you're running an origin server and offering a
              > JSON serialization for Atom content, anyone building a client to consume
              > that JSON will have their client break if/when you change syntax to
              > support a standardized solution, due to tight coupling -- which isn't an
              > issue when standard media types are adhered to.
              >
              > Whereas, if you only offer Atom, client developers can always add a
              > layer (using, say, XSLT) which transforms your Atom into their desired
              > JSON. If/when a standardized solution to that problem evolves, the
              > client developer can decide whether or not to support it -- nothing
              > breaks, so you're not in a position where you need to support legacy
              > code by adding conneg on application/x.atom+json vs. application/atom+
              > json, which increases the complexity of your system.
              >
              > I don't know your requirements, but I'd wait until the desired feature
              > (Atom serialized as JSON) actually exists before implementing it, rather
              > than trying to hit a moving target. Once application/atom+json is
              > nailed down, it's easy enough to add in support to please client
              > developers, without the extra complexity of supporting legacy code.
              > Client developers can then remove their transformation layer, and change
              > their Accept: header to request atom+json instead of atom+xml.
              >
              > In the meantime, there are benefits to be had from serving Atom as Atom,
              > which are a long ways off for Atom serialized as JSON. Intermediaries
              > aren't just caches, those with knowledge of Atom can prefetch DNS
              > lookups, or atom:entry documents, or images etc. while third-party
              > systems (i.e. Google) know how to handle (index, subscribe to) your
              > data. As a REST true believer, I don't see the benefit of trading away
              > this global, ubiquitous support of any system for the sake of easier
              > development of tightly-coupled clients. Or, for byte shaving, which is
              > a moot point when compression and caching are considered.
              >
              > http://tech.groups.yahoo.com/group/rest-discuss/message/8873
              >
              > Put another way, REST enables serendipitous re-use by all sorts of apps
              > which have no knowledge of your system specifics. Why give that up to
              > support the comparatively tiny number of applications developed
              > specifically for your system? OK, sure, you can use conneg, but if the
              > tiny number of purpose-built clients accounts for most of your users
              > you're just shooting yourself in the foot -- their usage won't be
              > accelerated via serendipitous re-use, and will degrade cache efficiency
              > for any ubiquitous-media-type representations you're serving.
              >
              > I think when Roy says "engineer for serendipity" it applies to runtime,
              > but is commonly misinterpreted to apply to design-time, which has led
              > lots of folks to implement multiple serializations. I don't think Roy
              > means "make it easier for third parties to write clients" so much as
              > "support those clients already existing as part of the deployed
              > infrastructure" because that's what allows a system to truly scale. By
              > doing so, your system will automatically support any new clients added
              > to the deployed infrastructure, which are based on the same standards
              > you've adhered to. You don't need to know about them, and they don't
              > need to know about you, which sounds pretty serendipitous to me.
              >
              > By clients, I mean both client connectors on intermediaries, and such
              > things as googlebot. Target those by using ubiquitous media types which
              > properly describe the linking/embedding semantics of your data.
              >
              > -Eric



              --
              Le doute n'est pas une condition agréable, mais la certitude est absurde.
            • Erik Wilde
              hello eric. ... is there an ongoing activity for this? afaict, many people want to use atom s model in JSON, and many create custom mappings. the problem with
              Message 6 of 8 , Sep 7, 2012
              • 0 Attachment
                hello eric.

                On 2012-09-06 20:52 , Eric J. Bowman wrote:
                > I don't know your requirements, but I'd wait until the desired feature
                > (Atom serialized as JSON) actually exists before implementing it, rather
                > than trying to hit a moving target. Once application/atom+json is
                > nailed down, it's easy enough to add in support to please client
                > developers, without the extra complexity of supporting legacy code.
                > Client developers can then remove their transformation layer, and change
                > their Accept: header to request atom+json instead of atom+xml.

                is there an ongoing activity for this? afaict, many people want to use
                atom's model in JSON, and many create custom mappings. the problem with
                a standard is that atom is fairly tightly narrowed to XML, in particular
                when you look at its extension model, and it seems to me the two
                fundamental options you have are both not that appealing (which i think
                is why we do not have atom in JSON yet):

                - leave out the complicated XMLy parts and end up with something that is
                only a subset of atom's model and thus cannot represent all possible
                atom+xml documents. not good.

                - map everything to JSON and end up with sometimes horrible JSON, in
                particular when people use extensions and these extensions contain XML
                markup. not good.

                i am just curious (because you recommended to "wait") how you think this
                dilemma will be solved, and whether you know about an activity where
                people are actively working on a solution.

                thanks and cheers,

                dret.

                --
                erik wilde | mailto:dret@... - tel:+1-510-2061079 |
                | UC Berkeley - School of Information (ISchool) |
                | http://dret.net/netdret http://twitter.com/dret |
              • Peter Williams
                ... Putting alternate links in the body is ok, but putting them in the HTTP header as link header fields[1] would better. It would make them visible to clients
                Message 7 of 8 , Sep 7, 2012
                • 0 Attachment
                  On Thu, Sep 6, 2012 at 3:18 PM, Greg Young <gregoryyoung1@...> wrote:
                  >
                  > Would it seem off to you that I gave you the alternates?

                  Putting alternate links in the body is ok, but putting them in the
                  HTTP header as link header fields[1] would better. It would make them
                  visible to clients that do not understand how to interprete your
                  particular flavor of JSON. Those clients are likely to be the ones
                  that need alternate links the most.

                  Also, you should strongly consider identifying your flavor of JSON
                  with a vendor media type. Doing so allows clients to request (and
                  interprete) its particular semantics. Having a specific media type is
                  particularly helpful if/when you are going to serve more than one
                  flavor of JSON. For example, if a standard atom+json ever really did
                  come to fruition you would probably want to support both, for a while
                  at least.

                  [1]: http://tools.ietf.org/html/rfc5988

                  Peter
                  barelyenough.org
                • Greg Young
                  Thats already there I just posted one of the formats of atom that can be gotten (+xml is also supported as is text + html) it depends what you send in your
                  Message 8 of 8 , Sep 7, 2012
                  • 0 Attachment
                    Thats already there I just posted one of the formats of atom that can be gotten (+xml is also supported as is text + html) it depends what you send in your accept header or url (yes I know this is "bad" but dealt with many that have problems getting headers working in their environments)

                    The question was more is it worthwhile to send all of them if you have already picked one but I guess its fine to send. Guess it makes sense though that in some use case you could want one one way and another another way.

                    re: mediatype we switched it.

                    Cheers,

                    Greg 

                    On Fri, Sep 7, 2012 at 10:09 AM, Peter Williams <pezra@...> wrote:
                     

                    On Thu, Sep 6, 2012 at 3:18 PM, Greg Young <gregoryyoung1@...> wrote:
                    >
                    > Would it seem off to you that I gave you the alternates?

                    Putting alternate links in the body is ok, but putting them in the
                    HTTP header as link header fields[1] would better. It would make them
                    visible to clients that do not understand how to interprete your
                    particular flavor of JSON. Those clients are likely to be the ones
                    that need alternate links the most.

                    Also, you should strongly consider identifying your flavor of JSON
                    with a vendor media type. Doing so allows clients to request (and
                    interprete) its particular semantics. Having a specific media type is
                    particularly helpful if/when you are going to serve more than one
                    flavor of JSON. For example, if a standard atom+json ever really did
                    come to fruition you would probably want to support both, for a while
                    at least.

                    [1]: http://tools.ietf.org/html/rfc5988

                    Peter
                    barelyenough.org




                    --
                    Le doute n'est pas une condition agréable, mais la certitude est absurde.
                  Your message has been successfully submitted and would be delivered to recipients shortly.