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

Re: [rest-discuss] PUT/POST content type hints

Expand Messages
  • Avdi Grimm
    ... ...and for non-JSON? Is there any generic analog of JSON Schema s submission links for POSTs? -- Avdi
    Message 1 of 12 , May 10, 2010
    • 0 Attachment
      On Mon, May 10, 2010 at 4:40 PM, Kris Zyp <kris@...> wrote:
      > Discovery of POST actions is completely different than PUT (since
      > PUT's behavior is implied by a GET response). A JSON Schema can
      > describe possible POST actions with submission links, including an
      > acceptable content type (in the "enctype" property).

      ...and for non-JSON? Is there any generic analog of JSON Schema's
      submission links for POSTs?

      --
      Avdi
    • Avdi Grimm
      On Mon, May 10, 2010 at 4:55 PM, Guilherme Silveira ... So there s no way to safely discover an acceptable list of POST formats? The library must performs a
      Message 2 of 12 , May 10, 2010
      • 0 Attachment
        On Mon, May 10, 2010 at 4:55 PM, Guilherme Silveira
        <guilherme.silveira@...> wrote:
        > If POSTing is your system entry point, your rest library should guess a media type (+profile) and POST it, if it gets back a 415, try it with any of the media types that the server has told you it understands.

        So there's no way to safely discover an acceptable list of POST
        formats? The library must performs a potentially state-changing
        operation in order to get info about supported operations?

        It seems like there's an asymmetry here... HTTP provides copious ways
        to discover content type of representations, content types of linked
        resources, and alternative representations of resources; but when it
        comes to POSTing data the means of discovery are practically
        nonexistent.

        My interest, incidentally, is in making APIs explorable as a way to
        make them more accessible to developers. I have a project
        [http://github.com/avdi/rack-stereoscope%5d which seeks to put an
        explorable HTML frontend on API based solely on hints gleaned from
        from Link headers, content types, etc.; and I'm wondering if there are
        any general ways to structure services so that projects like
        Stereoscope can discover the shape of data expected to be POSTed and
        show that to a developer in a helpful way.

        --
        Avdi
      • mike amundsen
        Exposing and discovering POST and PUT options is done a couple different ways: 1) HTML uses templated inputs via the FORM and INPUT elements to tell clients
        Message 3 of 12 , May 10, 2010
        • 0 Attachment
          Exposing and discovering POST and PUT options is done a couple different ways:

          1) HTML uses templated inputs via the FORM and INPUT elements to tell
          clients how to handle both templated queries (FORM action="get") and
          templated writes (FORM action="post"). [1]

          2) AtomPub handles this by identifying two important links (Collection
          URI and Member URI) and instructing clients and servers that the
          Collection URI can be used to create members (via HTTP POST) and the
          Member URI can be used for both updating entires (via PUT) and
          removing entries (via HTTP DELETE) [2]

          The common thread here is that the details on how to discover the
          rules for writing data to the server is spelled out in the media type
          documentation. This is fine as long as you are using a media type
          that has these details delineated in the media-type (HTML,
          Atom/AtomPub, SMIL, etc). Data-Oriented media-types such as XML, JSON,
          RDF, CSV, etc do not have these read/write semantics defined and that
          can be a real bummer<g>.

          You can get around this limitation by documentation a set of link
          relations that your clients and servers will need to understand; by
          importing other sub-sets of media types (e.g. XForms for XML, etc.)
          into your representations and telling clients and servers to refer to
          related documentation for guidance; or you can design and document you
          own media-type that has all the necessary template and link relation
          details for your clients and servers to implement.

          mca
          http://amundsen.com/blog/

          [1] http://www.w3.org/TR/REC-html40/interact/forms.html#edef-FORM
          [2] http://tools.ietf.org/html/rfc5023#section-5


          On Mon, May 10, 2010 at 17:44, Avdi Grimm <avdi@...> wrote:
          > On Mon, May 10, 2010 at 4:55 PM, Guilherme Silveira
          > <guilherme.silveira@...> wrote:
          >> If POSTing is your system entry point, your rest library should guess a media type (+profile) and POST it, if it gets back a 415, try it with any of the media types that the server has told you it understands.
          >
          > So there's no way to safely discover an acceptable list of POST
          > formats? The library must performs a potentially state-changing
          > operation in order to get info about supported operations?
          >
          > It seems like there's an asymmetry here... HTTP provides copious ways
          > to discover content type of representations, content types of linked
          > resources, and alternative representations of resources; but when it
          > comes to POSTing data the means of discovery are practically
          > nonexistent.
          >
          > My interest, incidentally, is in making APIs explorable as a way to
          > make them more accessible to developers. I have a project
          > [http://github.com/avdi/rack-stereoscope%5d which seeks to put an
          > explorable HTML frontend on API based solely on hints gleaned from
          > from Link headers, content types, etc.; and I'm wondering if there are
          > any general ways to structure services so that projects like
          > Stereoscope can discover the shape of data expected to be POSTed and
          > show that to  a developer in a helpful way.
          >
          > --
          > Avdi
          >
          >
          > ------------------------------------
          >
          > Yahoo! Groups Links
          >
          >
          >
          >
        • Eric J. Bowman
          ... Absolutely not. The late binding of representation to resource precludes this assumption. HTML is capable of providing an interface to an Atom system.
          Message 4 of 12 , May 11, 2010
          • 0 Attachment
            Kris Zyp wrote:
            >
            > I believe one should be able to assume that the content type of the
            > representation returned from a server from GET for URI is acceptable
            > in a PUT request to that server for the same URI.
            >

            Absolutely not. The late binding of representation to resource
            precludes this assumption. HTML is capable of providing an interface
            to an Atom system. What media type to PUT or POST to the system is
            explicitly provided in the markup, i.e. a self-documenting interface.

            Assuming that you can PUT or POST HTML to my system because that's the
            media type I sent on GET would not work -- I derive HTML from Atom, not
            the other way around.

            A PUT of an HTML document would show an intent to replace the
            self-documenting interface provided by the HTML representation, with
            some other application state. HTML is generated by my system, it is not
            subject to change via PUT to negotiated resources which happen to return
            text/html or application/xhtml+xml on GET with a Web browser, but
            happen to return Atom to a feed reader.

            >
            > When using JSON,
            > additional information about acceptable property values can be
            > determined from any JSON Schema referenced by the resource. In other
            > words, if you GET some resource, and the server responds with:
            >
            > Content-Type: application/my-type+json; profile=my-schema
            >
            > One could retrieve the schema from the "my-schema" relative URI and do
            > a PUT using the application/my-type+json content type with the schema
            > information as a guide to what property values are acceptable.
            >

            Sure you can *do* this, it just wouldn't be REST. Leaving aside that
            the media type identifier definition for JSON doesn't say anything about
            extending it using *+json, the media type definition for JSON says
            nothing about HTTP methods. Where have you provided a self-documenting
            interface giving a target URI, method and media type -- as provided by
            forms languages having no corollary in JSON, yet required by REST?

            If you "just know" that you can PUT or DELETE some JSON resource, it's
            no more RESTful than "just knowing" that you can PUT or DELETE some
            JPEG. You're resorting to unbounded creativity, rather than using
            standard media types and link relations which *do* cover HTTP methods,
            for any target media type.

            >
            > Discovery of POST actions is completely different than PUT (since
            > PUT's behavior is implied by a GET response). A JSON Schema can
            > describe possible POST actions with submission links, including an
            > acceptable content type (in the "enctype" property).
            >

            I don't see how. Regardless of schema, there's simply no mention in
            the media type definition of JSON for describing URIs or methods, i.e.
            there's no forms language. The demo I posted consists of XHTML steady-
            states derived from various source representationss of other media
            types. These steady-states (will) provide a self-documenting API to
            the underlying Atom-based system.

            The user isn't trying to discover PUT vs. POST actions. The user is
            trying to drive an application to another steady-state. The user agent
            needs to translate that user goal into HTTP interactions. If the user
            is trying to add a new post, the user agent is instructed to POST to
            the domain root. If the user is trying to add a new comment, the user
            agent is instructed to POST to the appropriate comment thread. If the
            user intent is to edit an existing entry, the user agent is instructed
            to PUT to the existing URI. In each case, the user agent is instructed
            to use application/atom+xml; type=entry.

            There's no RESTful way to instruct any user agent that "this system
            uses Atom Protocol" and this may not be inferred by the fact that the
            system uses Atom. All I can do is provide a self-documenting hypertext
            API which instructs user agents how to interact with the system. This
            API may or may not conform to Atom Protocol. Whether it does or not is
            less important to REST than its presence.

            None of this is any different for a system based on JSON rather than
            Atom. As a REST system, I could change my Atom backend to a JSON
            backend on a whim. I'm not saying it would be easy, but I am saying
            that the application states wouldn't change. The HTML would still
            present a textarea, changes to that textarea would be submitted to the
            same URI, using whatever media type the form says to use -- all HTML
            user agents automatically update to the new API.

            If you need to guess what media type to use then you can't possibly be
            using REST. A REST API will always tell you exactly what media type to
            use. It isn't implicit in any guessable fashion, it's explicit. If it
            isn't explicit, it isn't REST. HTML says what POST does, but only your
            hypertext can specify media type, if you lack such hypertext you lack
            a critical REST constraint.

            -Eric
          • Mike Kelly
            Hey mike! Superb summary Do machine-focused media types actually have a requirement for templated writes (a la HTML)? What benefit would machine clients get
            Message 5 of 12 , May 11, 2010
            • 0 Attachment
              Hey mike!

              Superb summary

              Do machine-focused media types actually have a requirement for templated writes (a la HTML)? What benefit would machine clients get from that, given that they're programmed ahead of time anyway?

              Cheers,
              Mike


              On Mon, May 10, 2010 at 11:07 PM, mike amundsen <mamund@...> wrote:
              Exposing and discovering POST and PUT options is done a couple different ways:

              1) HTML uses templated inputs via the FORM and INPUT elements to tell
              clients how to handle both templated queries (FORM action="get") and
              templated writes (FORM action="post"). [1]

              2) AtomPub handles this by identifying two important links (Collection
              URI and Member URI) and instructing clients and servers that the
              Collection URI can be used to create members (via HTTP POST) and the
              Member URI can be used for both updating entires (via PUT) and
              removing entries (via HTTP DELETE) [2]

              The common thread here is that the details on how to discover the
              rules for writing data to the server is spelled out in the media type
              documentation.  This is fine as long as you are using a media type
              that has these details delineated in the media-type (HTML,
              Atom/AtomPub, SMIL, etc). Data-Oriented media-types such as XML, JSON,
              RDF, CSV, etc do not have these read/write semantics defined and that
              can be a real bummer<g>.

              You can get around this limitation by documentation a set of link
              relations that your clients and servers will need to understand; by
              importing other sub-sets of media types (e.g. XForms for XML, etc.)
              into your representations and telling clients and servers to refer to
              related documentation for guidance; or you can design and document you
              own media-type that has all the necessary template and link relation
              details for your clients and servers to implement.
              [1] http://www.w3.org/TR/REC-html40/interact/forms.html#edef-FORM
              [2] http://tools.ietf.org/html/rfc5023#section-5


              On Mon, May 10, 2010 at 17:44, Avdi Grimm <avdi@...> wrote:
              > On Mon, May 10, 2010 at 4:55 PM, Guilherme Silveira
              > <guilherme.silveira@...> wrote:
              >> If POSTing is your system entry point, your rest library should guess a media type (+profile) and POST it, if it gets back a 415, try it with any of the media types that the server has told you it understands.
              >
              > So there's no way to safely discover an acceptable list of POST
              > formats? The library must performs a potentially state-changing
              > operation in order to get info about supported operations?
              >
              > It seems like there's an asymmetry here... HTTP provides copious ways
              > to discover content type of representations, content types of linked
              > resources, and alternative representations of resources; but when it
              > comes to POSTing data the means of discovery are practically
              > nonexistent.
              >
              > My interest, incidentally, is in making APIs explorable as a way to
              > make them more accessible to developers. I have a project
              > [http://github.com/avdi/rack-stereoscope] which seeks to put an
              > explorable HTML frontend on API based solely on hints gleaned from
              > from Link headers, content types, etc.; and I'm wondering if there are
              > any general ways to structure services so that projects like
              > Stereoscope can discover the shape of data expected to be POSTed and
              > show that to  a developer in a helpful way.
              >
              > --
              > Avdi
              >
              >
              > ------------------------------------
              >
              > Yahoo! Groups Links
              >
              >
              >
              >


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

              Yahoo! Groups Links

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

              <*> Your email settings:
                 Individual Email | Traditional

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

              <*> To change settings via email:
                 rest-discuss-digest@yahoogroups.com
                 rest-discuss-fullfeatured@yahoogroups.com

              <*> To unsubscribe from this group, send an email to:
                 rest-discuss-unsubscribe@yahoogroups.com

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


            • Kris Zyp
              ... Hash: SHA1 ... I definitely agree that this assumption can be wrong, and a 415 could be returned with directions about what media type is acceptable. Or
              Message 6 of 12 , May 11, 2010
              • 0 Attachment
                -----BEGIN PGP SIGNED MESSAGE-----
                Hash: SHA1
                 


                On 5/11/2010 4:31 AM, Eric J. Bowman wrote:

                >
                > Kris Zyp wrote:
                > >
                > > I believe one should be able to assume that the content type of the
                > > representation returned from a server from GET for URI is acceptable
                > > in a PUT request to that server for the same URI.
                > >
                >
                > Absolutely not. The late binding of representation to resource
                > precludes this assumption. HTML is capable of providing an interface
                > to an Atom system. What media type to PUT or POST to the system is
                > explicitly provided in the markup, i.e. a self-documenting interface.
                >
                > Assuming that you can PUT or POST HTML to my system because that's the
                > media type I sent on GET would not work -- I derive HTML from Atom, not
                > the other way around.
                >
                > A PUT of an HTML document would show an intent to replace the
                > self-documenting interface provided by the HTML representation, with
                > some other application state. HTML is generated by my system, it is not
                > subject to change via PUT to negotiated resources which happen to return
                > text/html or application/xhtml+xml on GET with a Web browser, but
                > happen to return Atom to a feed reader.
                >


                I definitely agree that this assumption can be wrong, and a 415 could
                be returned with directions about what media type is acceptable. Or
                the client's preferred media type may override the GET's content type
                (in which case he probably wouldn't be asking this question). But
                requiring a client to simply "know" what media type the server needs
                (when the client could encode in multiple media types) rather than
                attempting to use the same media type from a GET would obviously
                require out of band information and badly violate REST.

                >
                > >
                > > When using JSON,
                > > additional information about acceptable property values can be
                > > determined from any JSON Schema referenced by the resource. In other
                > > words, if you GET some resource, and the server responds with:
                > >
                > > Content-Type: application/my-type+json; profile=my-schema
                > >
                > > One could retrieve the schema from the "my-schema" relative URI and do
                > > a PUT using the application/my-type+json content type with the schema
                > > information as a guide to what property values are acceptable.
                > >
                >
                > Sure you can *do* this, it just wouldn't be REST. Leaving aside that
                > the media type identifier definition for JSON doesn't say anything about
                > extending it using *+json, the media type definition for JSON says
                > nothing about HTTP methods. Where have you provided a self-documenting
                > interface giving a target URI, method and media type -- as provided by
                > forms languages having no corollary in JSON, yet required by REST?
                >
                >
                > If you "just know" that you can PUT or DELETE some JSON resource, it's
                > no more RESTful than "just knowing" that you can PUT or DELETE some
                > JPEG. You're resorting to unbounded creativity, rather than using
                > standard media types and link relations which *do* cover HTTP methods,
                > for any target media type.
                >


                RFC 2616 is sufficient for describing the semantics of PUT and DELETE.
                I don't need to know anything besides what RFC 2616 has clearly described.

                >
                > >
                > > Discovery of POST actions is completely different than PUT (since
                > > PUT's behavior is implied by a GET response). A JSON Schema can
                > > describe possible POST actions with submission links, including an
                > > acceptable content type (in the "enctype" property).
                > >
                >
                > I don't see how. Regardless of schema, there's simply no mention in
                > the media type definition of JSON for describing URIs or methods, i.e.
                > there's no forms language. The demo I posted consists of XHTML steady-
                > states derived from various source representationss of other media
                > types. These steady-states (will) provide a self-documenting API to
                > the underlying Atom-based system.
                >


                JSON Schema effectively provides a forms language:
                http://tools.ietf.org/html/draft-zyp-json-schema-02
                >
                >
                > The user isn't trying to discover PUT vs. POST actions. The user is
                > trying to drive an application to another steady-state. The user agent
                > needs to translate that user goal into HTTP interactions. If the user
                > is trying to add a new post, the user agent is instructed to POST to
                > the domain root. If the user is trying to add a new comment, the user
                > agent is instructed to POST to the appropriate comment thread. If the
                > user intent is to edit an existing entry, the user agent is instructed
                > to PUT to the existing URI. In each case, the user agent is instructed
                > to use application/atom+xml; type=entry.
                >
                > There's no RESTful way to instruct any user agent that "this system
                > uses Atom Protocol" and this may not be inferred by the fact that the
                > system uses Atom. All I can do is provide a self-documenting hypertext
                > API which instructs user agents how to interact with the system. This
                > API may or may not conform to Atom Protocol. Whether it does or not is
                > less important to REST than its presence.
                >
                > None of this is any different for a system based on JSON rather than
                > Atom. As a REST system, I could change my Atom backend to a JSON
                > backend on a whim. I'm not saying it would be easy, but I am saying
                > that the application states wouldn't change. The HTML would still
                > present a textarea, changes to that textarea would be submitted to the
                > same URI, using whatever media type the form says to use -- all HTML
                > user agents automatically update to the new API.
                >
                > If you need to guess what media type to use then you can't possibly be
                > using REST. A REST API will always tell you exactly what media type to
                > use. It isn't implicit in any guessable fashion, it's explicit. If it
                > isn't explicit, it isn't REST. HTML says what POST does, but only your
                > hypertext can specify media type, if you lack such hypertext you lack
                > a critical REST constraint.
                >


                Absolutely, I agree.

                - --
                Kris Zyp
                SitePen
                (503) 806-1841
                http://sitepen.com
                -----BEGIN PGP SIGNATURE-----
                Version: GnuPG v1.4.9 (MingW32)
                Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
                 
                iEYEARECAAYFAkvpUc4ACgkQ9VpNnHc4zAyE7wCcCjIsRLOPR9UmAvJj50z9whT/
                5fsAn2gCtvWZto0PD4c/WeRUAGyMUZJE
                =mp4f
                -----END PGP SIGNATURE-----

              • Eric J. Bowman
                ... I don t follow. The media type of a response to a GET request is a function of the client s Accept request header. To override conneg, one uses the URI
                Message 7 of 12 , May 11, 2010
                • 0 Attachment
                  Kris Zyp wrote:
                  >
                  > > >
                  > > > I believe one should be able to assume that the content type of
                  > > > the representation returned from a server from GET for URI is
                  > > > acceptable in a PUT request to that server for the same URI.
                  > > >
                  > >
                  > > Absolutely not. The late binding of representation to resource
                  > > precludes this assumption. HTML is capable of providing an interface
                  > > to an Atom system. What media type to PUT or POST to the system is
                  > > explicitly provided in the markup, i.e. a self-documenting
                  > > interface.
                  > >
                  > > Assuming that you can PUT or POST HTML to my system because that's
                  > > the media type I sent on GET would not work -- I derive HTML from
                  > > Atom, not the other way around.
                  > >
                  > > A PUT of an HTML document would show an intent to replace the
                  > > self-documenting interface provided by the HTML representation, with
                  > > some other application state. HTML is generated by my system, it is
                  > > not subject to change via PUT to negotiated resources which happen
                  > > to return text/html or application/xhtml+xml on GET with a Web
                  > > browser, but happen to return Atom to a feed reader.
                  > >
                  >
                  > I definitely agree that this assumption can be wrong, and a 415 could
                  > be returned with directions about what media type is acceptable. Or
                  > the client's preferred media type may override the GET's content type
                  > (in which case he probably wouldn't be asking this question).
                  >

                  I don't follow. The media type of a response to a GET request is a
                  function of the client's Accept request header. To "override" conneg,
                  one uses the URI assigned to the desired variant, instead of the
                  negotiated URI. The client's desired media type will in no way affect
                  a non-negotiated resource.

                  On my system, one may directly dereference Atom representations by
                  using .atom extensions -- each variant representation is a resource in
                  its own right. Even so, REST isn't based on making assumptions about
                  being able to PUT that .atom file back after editing it, by virtue of
                  its media type being application/atom+xml.

                  The only allowable change for the requesting user, may be to change the
                  tags associated with a post. This could be done via PATCH, or via PUT
                  to a subordinate resource, in either case using application/atomcat+xml.
                  Only the hypertext API can tell me this.

                  In REST, these specifics are communicated via hypertext. A user agent
                  following its nose couldn't possibly run into a 415 error. If it does,
                  the correct response from the broken server that led the user agent
                  astray in the first place with incorrect hypertext, should be 500.

                  I suspect you're expecting your dog to throw you the frisbee... ;-)

                  >
                  > But
                  > requiring a client to simply "know" what media type the server needs
                  > (when the client could encode in multiple media types) rather than
                  > attempting to use the same media type from a GET would obviously
                  > require out of band information and badly violate REST.
                  >

                  No, both are equally bad violations of REST. What media type to
                  associate with a PUT, POST or PATCH request must be explicitly stated
                  in the hypertext which instructs user agents *how* to make PUT, POST or
                  PATCH requests (by "how" I mean, is the request required by the system
                  to be conditional, and such).

                  If you're relying on the assumption that the media type returned with a
                  GET has anything to do with instructing the client what media type to
                  use for PUT, POST or PATCH then your API is based on out-of-band
                  information that is not common knowledge encompassed within a media
                  type definition.

                  >
                  > RFC 2616 is sufficient for describing the semantics of PUT and DELETE.
                  > I don't need to know anything besides what RFC 2616 has clearly
                  > described.
                  >

                  Yes, you do, in REST. HTTP describes a range of possible semantics for
                  some methods. REST APIs must describe the specific method semantics as
                  implemented on your system, using standard media types. HTTP allows you
                  to DELETE an Atom Media Entry. REST constrains that deletion to behave
                  in accordance with the media type, i.e. the media file must also be
                  deleted.

                  DELETE behavior on a collection resource is undefined in HTTP and Atom,
                  meaning the Atom media type allows different behaviors. So a REST API
                  must self-document the DELETE behavior on collections, or even offer
                  the user a choice of behaviors. HTTP does not a REST API make, there
                  must be hypertext instructing the user agent *how* to DELETE.

                  >
                  > JSON Schema effectively provides a forms language:
                  > http://tools.ietf.org/html/draft-zyp-json-schema-02
                  >

                  I'm sure you know more about the workings of the IETF than I do, but I
                  don't see how you can register application/schema+json without first
                  revising the JSON media type identifier definition to allow for this
                  extensibility. You should also reference RFC 3986, rather than 2396.

                  In my opinion, JSON lacks the basis for a schema language which defines
                  linking and forms. This is significantly beyond the scope of JSON-as-
                  written. What you're after is a schema language for application/
                  hyperjson, i.e. first you need a structured JSON language, then you
                  have the basis for schema on top of it. Or somesuch.

                  "This specification is protocol agnostic. The underlying protocol
                  (such as HTTP) should sufficiently define the semantics of the
                  client-server interface, the retrieval of resource representations
                  linked to by JSON representations, and modification of those
                  resources."

                  Not really. HTML markup implies GET in several ways, in addition to
                  defining GET as used in forms, but does not specify protocol. Standard
                  methods are cross-protocol, with protocol determined by the URI. An
                  HTML form can just as easily GET and PUT FTP URIs as HTTP URIs. This is
                  part of the protocol-agnostic REST style, which relies on standard
                  media types to constrain method semantics (or hypertext, where the
                  media type lacks such constraints).

                  Atom Protocol, for example, constrains the application/atom+xml media
                  type's method implementation. HTTP allows PUT to create and/or replace
                  a resource. REST constrains PUT to mean either create or replace for
                  all resources on your system -- varying PUT semantics by media type is
                  not allowed.

                  In a REST system which implements Atom Protocol, PUT is constrained to
                  replacement semantics by the application/atom+xml media type. Creation
                  semantics are assigned to POST. The underlying protocol does _not_
                  sufficiently define these semantics for REST, because the REST style is
                  protocol-agnostic.

                  Method semantics are defined by the protocols which implement them
                  (HTTP, FTP etc.). In REST, method implementation is constrained by
                  media type (or API). If Atom Protocol method semantics were left to the
                  underlying protocol, there wouldn't be interoperability because some
                  systems would use PUT to create, while other systems would use POST, due
                  to the unconstrained nature of standard method semantics.

                  If a JSON schema language is to be of any use in REST development, then
                  it must allow for the constraint of standard method semantics. So
                  first, there must be a JSON language which provides data structures for
                  traversal of a link (as with <a href>) vs. inclusion of a link (as with
                  <img src/>) vs. processing instructions (as with <link rel=
                  'stylesheet'/>), I think.

                  Note that the media type, as with HTML, would define all of these cases
                  as GET. What your draft lacks, is any means to instruct user agents to
                  fetch a resource for inclusion, vs. traversing the link and presenting
                  the retrieved representation as the next steady-state. There's also no
                  way to communicate constraints on method semantics, i.e. to assign PUT
                  replacement semantics and assign POST creation semantics, or vice-versa
                  depending on the needs of the schema/API developer.

                  I believe what you're trying is possible, but it's my opinion that you
                  have enough in there for two separate proposals, while lacking the tools
                  I would need to implement it as a REST developer.

                  -Eric
                • Kris Zyp
                  ... Hash: SHA1 ... I certainly agree that receiving a media type from a server does not guarantee that a server can receive that same media type from the
                  Message 8 of 12 , May 24, 2010
                  • 0 Attachment
                    -----BEGIN PGP SIGNED MESSAGE-----
                    Hash: SHA1



                    On 5/11/2010 4:31 AM, Eric J. Bowman wrote:
                    > Kris Zyp wrote:
                    >>
                    >> I believe one should be able to assume that the content type of the
                    >> representation returned from a server from GET for URI is acceptable
                    >> in a PUT request to that server for the same URI.
                    >>
                    >
                    > Absolutely not. The late binding of representation to resource
                    > precludes this assumption. HTML is capable of providing an interface
                    > to an Atom system. What media type to PUT or POST to the system is
                    > explicitly provided in the markup, i.e. a self-documenting interface.
                    >
                    > Assuming that you can PUT or POST HTML to my system because that's the
                    > media type I sent on GET would not work -- I derive HTML from Atom, not
                    > the other way around.
                    >
                    > A PUT of an HTML document would show an intent to replace the
                    > self-documenting interface provided by the HTML representation, with
                    > some other application state. HTML is generated by my system, it is not
                    > subject to change via PUT to negotiated resources which happen to return
                    > text/html or application/xhtml+xml on GET with a Web browser, but
                    > happen to return Atom to a feed reader.

                    I certainly agree that receiving a media type from a server does not
                    guarantee that a server can receive that same media type from the
                    client. However, in the absence of knowledge of a different explicit
                    media type preference (from the media type definition) when it comes
                    to negotiating an acceptable type with the server, pretending the all
                    media types are equally likely is as silly as pretending that any
                    language is any equally likely to be understood in response to someone
                    who speaks to you in french.
                    >
                    >>
                    >> When using JSON,
                    >> additional information about acceptable property values can be
                    >> determined from any JSON Schema referenced by the resource. In other
                    >> words, if you GET some resource, and the server responds with:
                    >>
                    >> Content-Type: application/my-type+json; profile=my-schema
                    >>
                    >> One could retrieve the schema from the "my-schema" relative URI and do
                    >> a PUT using the application/my-type+json content type with the schema
                    >> information as a guide to what property values are acceptable.
                    >>
                    >
                    > Sure you can *do* this, it just wouldn't be REST. Leaving aside that
                    > the media type identifier definition for JSON doesn't say anything about
                    > extending it using *+json, the media type definition for JSON says
                    > nothing about HTTP methods. Where have you provided a self-documenting
                    > interface giving a target URI, method and media type -- as provided by
                    > forms languages having no corollary in JSON, yet required by REST?
                    >
                    > If you "just know" that you can PUT or DELETE some JSON resource, it's
                    > no more RESTful than "just knowing" that you can PUT or DELETE some
                    > JPEG. You're resorting to unbounded creativity, rather than using
                    > standard media types and link relations which *do* cover HTTP methods,
                    > for any target media type.
                    >

                    RFC2616 sufficiently defines the meaning of PUT and DELETE, a media
                    type does not need to conflate protocol concerns to be RESTful.
                    >>
                    >> Discovery of POST actions is completely different than PUT (since
                    >> PUT's behavior is implied by a GET response). A JSON Schema can
                    >> describe possible POST actions with submission links, including an
                    >> acceptable content type (in the "enctype" property).
                    >>
                    >
                    > I don't see how. Regardless of schema, there's simply no mention in
                    > the media type definition of JSON for describing URIs or methods, i.e.
                    > there's no forms language. The demo I posted consists of XHTML steady-
                    > states derived from various source representationss of other media
                    > types. These steady-states (will) provide a self-documenting API to
                    > the underlying Atom-based system.
                    >
                    > The user isn't trying to discover PUT vs. POST actions. The user is
                    > trying to drive an application to another steady-state. The user agent
                    > needs to translate that user goal into HTTP interactions. If the user
                    > is trying to add a new post, the user agent is instructed to POST to
                    > the domain root. If the user is trying to add a new comment, the user
                    > agent is instructed to POST to the appropriate comment thread. If the
                    > user intent is to edit an existing entry, the user agent is instructed
                    > to PUT to the existing URI. In each case, the user agent is instructed
                    > to use application/atom+xml; type=entry.
                    >
                    > There's no RESTful way to instruct any user agent that "this system
                    > uses Atom Protocol" and this may not be inferred by the fact that the
                    > system uses Atom. All I can do is provide a self-documenting hypertext
                    > API which instructs user agents how to interact with the system. This
                    > API may or may not conform to Atom Protocol. Whether it does or not is
                    > less important to REST than its presence.
                    >
                    > None of this is any different for a system based on JSON rather than
                    > Atom. As a REST system, I could change my Atom backend to a JSON
                    > backend on a whim. I'm not saying it would be easy, but I am saying
                    > that the application states wouldn't change. The HTML would still
                    > present a textarea, changes to that textarea would be submitted to the
                    > same URI, using whatever media type the form says to use -- all HTML
                    > user agents automatically update to the new API.
                    >
                    > If you need to guess what media type to use then you can't possibly be
                    > using REST. A REST API will always tell you exactly what media type to
                    > use. It isn't implicit in any guessable fashion, it's explicit. If it
                    > isn't explicit, it isn't REST. HTML says what POST does, but only your
                    > hypertext can specify media type, if you lack such hypertext you lack
                    > a critical REST constraint.
                    There is certainly nothing wrong with a specifying what media type a
                    server can handle in the media type definition or hypertext (JSON
                    Schema allows for specifying an acceptable media type for requests as
                    well), however the dynamic representation/content negotiation
                    principle implies that a server may have capabilities to handle
                    various types that may independently evolve. I know my server software
                    can handle various media types to update resources (JSON, JS, XML,
                    url-encoded, etc.).

                    - --
                    Kris Zyp
                    SitePen
                    (503) 806-1841
                    http://sitepen.com
                    -----BEGIN PGP SIGNATURE-----
                    Version: GnuPG v1.4.9 (MingW32)
                    Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

                    iEYEARECAAYFAkv66cIACgkQ9VpNnHc4zAzASwCfeoeiGm7w2B4FmGssIaKfGafj
                    t94An13EQXdWwHtvIC777FS9cXdL5pqn
                    =x8xU
                    -----END PGP SIGNATURE-----
                  • Eric J. Bowman
                    (Unreferenced citations in my posts here, as always, come from Roy s thesis.) (Long, lecture-y posts, as always, come about when I feel that fundamental
                    Message 9 of 12 , May 30, 2010
                    • 0 Attachment
                      (Unreferenced citations in my posts here, as always, come from Roy's
                      thesis.)

                      (Long, lecture-y posts, as always, come about when I feel that
                      fundamental violations of Web architecture are being discussed.)

                      Kris Zyp wrote:
                      >
                      > On 5/11/2010 4:31 AM, Eric J. Bowman wrote:
                      > > Kris Zyp wrote:
                      > >>
                      > >> I believe one should be able to assume that the content type of the
                      > >> representation returned from a server from GET for URI is
                      > >> acceptable in a PUT request to that server for the same URI.
                      > >>
                      > >
                      > > Absolutely not. The late binding of representation to resource
                      > > precludes this assumption. HTML is capable of providing an
                      > > interface to an Atom system. What media type to PUT or POST to the
                      > > system is explicitly provided in the markup, i.e. a
                      > > self-documenting interface.
                      > >
                      > > Assuming that you can PUT or POST HTML to my system because that's
                      > > the media type I sent on GET would not work -- I derive HTML from
                      > > Atom, not the other way around.
                      > >
                      > > A PUT of an HTML document would show an intent to replace the
                      > > self-documenting interface provided by the HTML representation, with
                      > > some other application state. HTML is generated by my system, it
                      > > is not subject to change via PUT to negotiated resources which
                      > > happen to return text/html or application/xhtml+xml on GET with a
                      > > Web browser, but happen to return Atom to a feed reader.
                      >
                      > I certainly agree that receiving a media type from a server does not
                      > guarantee that a server can receive that same media type from the
                      > client. However, in the absence of knowledge of a different explicit
                      > media type preference (from the media type definition) when it comes
                      > to negotiating an acceptable type with the server, pretending the all
                      > media types are equally likely is as silly as pretending that any
                      > language is any equally likely to be understood in response to someone
                      > who speaks to you in french.
                      >

                      I don't pretend that my website output will be understood by someone
                      whose browser indicates that they only know French. But, I can respond
                      406 with the default English variant as entity-body, because it's the
                      best representation I have. I "send whatever is most likely to be
                      optimal first and then provide a list of alternatives for the client to
                      retrieve if the first response is unsatisfactory."

                      The French user's browser may not know that the user also understands
                      the German variant of my (hypothetical) website, but the French user
                      may recover from the unintelligible English variant by selecting the
                      German variant, via link rel='alternate' elements or headers with lang
                      attributes presented in browser chrome, or via links displayed within
                      page content (the latter being WAI-approved).

                      Don't work around REST's respond-first-recover-later approach by trying
                      to first determine the optimal response, by making guesses about what
                      the system isn't telling you -- just respond to what the system *is*
                      telling you. In REST, error recovery only occurs _after_ the error,
                      as the error response itself may be the mechanism through which such
                      recovery occurs.

                      (If content is moved to another site, the proper response is a 301
                      redirect -- unless that site's policy forbids deep linking, in which
                      case the link may be displayed as text in the body of a 410 response,
                      with instructions to cut-and-paste. Regardless of whether conneg is
                      involved, and if so, regardless as to whether it's language-based or
                      media-type-based, errors must be allowed to occur instead of trying to
                      head them off by guessing anything.)

                      If there is some absence of knowledge of media type preference, it is
                      an error with the coding of the system, or as Roy put it so eloquently,
                      a case of playing frisbee with your dog backwards. A resource may
                      indicate via an Accept (or Accept-Patch) header, what media types it
                      understands. A user agent following its nose may be instructed to send
                      a POST as multipart/form-data containing text/plain, but determine from
                      a HEAD request to the target that application/atom+xml is also Accept-ed
                      (while also confirming that POST is Allow-ed), and send that instead.

                      Done properly, REST removes any need to make any guesses about metadata,
                      in any situation. The user agent is always instructed as to what it
                      can do, so any code attempting to infer what to do in the absence of
                      some piece of knowledge is solving the problem backwards, i.e.
                      expecting the dog to throw the frisbee.

                      If user agents aren't being instructed properly, fix the system such
                      that they are, instead of "fixing" the user agents to infer "properly"
                      according to some sniffing algorithm. Such sniffing algorithms may be
                      necessary in real-world browser development, but are anathema to REST.

                      >
                      > >
                      > >>
                      > >> When using JSON,
                      > >> additional information about acceptable property values can be
                      > >> determined from any JSON Schema referenced by the resource. In
                      > >> other words, if you GET some resource, and the server responds
                      > >> with:
                      > >>
                      > >> Content-Type: application/my-type+json; profile=my-schema
                      > >>
                      > >> One could retrieve the schema from the "my-schema" relative URI
                      > >> and do a PUT using the application/my-type+json content type with
                      > >> the schema information as a guide to what property values are
                      > >> acceptable.
                      > >>
                      > >
                      > > Sure you can *do* this, it just wouldn't be REST. Leaving aside
                      > > that the media type identifier definition for JSON doesn't say
                      > > anything about extending it using *+json, the media type definition
                      > > for JSON says nothing about HTTP methods. Where have you provided
                      > > a self-documenting interface giving a target URI, method and media
                      > > type -- as provided by forms languages having no corollary in JSON,
                      > > yet required by REST?
                      > >
                      > > If you "just know" that you can PUT or DELETE some JSON resource,
                      > > it's no more RESTful than "just knowing" that you can PUT or DELETE
                      > > some JPEG. You're resorting to unbounded creativity, rather than
                      > > using standard media types and link relations which *do* cover HTTP
                      > > methods, for any target media type.
                      > >
                      >
                      > RFC2616 sufficiently defines the meaning of PUT and DELETE, a media
                      > type does not need to conflate protocol concerns to be RESTful.
                      >

                      As I've said many times, media types don't redefine or override method
                      definitions (saying this PUT is actually a PATCH in the presence of
                      such-and-such media type, is kinjiru). However, a media type which
                      constrains the scope of *possible* method semantics to a *specific*
                      behavior is not conflating anything.

                      "
                      The data format of a representation is known as a media type. A
                      representation can be included in a message and processed by the
                      recipient according to the control data of the message and the nature
                      of the media type. Some media types are intended for automated
                      processing, some are intended to be rendered for viewing by a user, and
                      a few are capable of both. Composite media types can be used to enclose
                      multiple representations in a single message.
                      "

                      In fact, such media types are required for REST systems to process
                      requests, since REST systems rely on the combination of control data
                      and "the nature of the media type". Stating "see RFC2616" indicates a
                      worldview where the nature of the media type is irrelevant to request
                      processing. This is (one reason) why we're so fond of saying HTTP !=
                      REST here.

                      REST is protocol-agnostic. By introducing a stream transducer to
                      automate name-value-pair handling for SMTP messages to a standard
                      listmail, I can implement an HTML-based REST application using forms'
                      @method='post' @action='mailto:group@listmail'. The next application
                      steady-state is displayed when the next response to the thread hits
                      the INBOX. The only over-the-wire protocol used in such a scenario is
                      SMTP.

                      This is why I consider it an error that HTML defines protocol-specific
                      method semantics instead of generic method semantics. But, far from
                      conflating protocol concerns, HTML manages to constrain the use of HTTP
                      to specific media types for specific methods. You can send any media
                      type with a POST, it just has to be declared within multipart/form-data.

                      http://www.w3.org/TR/html401/interact/forms.html#h-17.13.1

                      Notice how removing the string "HTTP" from that section changes it to
                      be inclusive of other protocols like FTP or SMTP which, in practice,
                      already work with HTML forms anyway? Saying "see RFC2616" tends to
                      imply that the media type is not to be transferred over other protocols
                      (like XMPP). Are you sure you want a JSON schema language which
                      restricts JSON to HTTP-only implementations? This may be fine for Atom
                      Protocol, but it's an odd choice for a schema language.

                      HTTP, in REST, is an application protocol based on media type, not a
                      media-type-agnostic transport protocol like FTP. A system which
                      processes requests based strictly on the control data (as opposed to
                      request processing based on the combination of control data + media
                      type), may as well be using FTP. Most REST claimants are really HTTP-
                      RPC, because they're using HTTP as FTP with caching -- still just a
                      transport protocol.

                      While RESTful interaction is possible over FTP, SMTP or even XMPP, only
                      HTTP exists (so far) as a true RESTful application protocol. That's why
                      it's entirely appropriate that Atom Protocol chose HTTP method semantics
                      (both constraining and defining their behavior, i.e. PUT only replaces
                      but doesn't create, and DELETE on a media entry also deletes the media
                      file, neither of which changes the semantics of either method) rather
                      than generic semantics; HTTP's application-protocol capabilities (like
                      conditional requests) just aren't present in other protocols.

                      Using HTTP as a transport protocol results in HTTP-RPC implementations,
                      like the sparse-bit array solution Roy hypothesizes, here:

                      "
                      I should also note that the above is not yet fully RESTful, at least
                      how I use the term. All I have done is described the service
                      interfaces, which is no more than any RPC. In order to make it RESTful,
                      I would need to add hypertext to introduce and define the service,
                      describe how to perform the mapping using forms and/or link templates,
                      and provide code to combine the visualizations in useful ways. I could
                      even go further and define these relationships as a standard, much like
                      Atom has standardized a normal set of HTTP relationships with expected
                      semantics, but I have bigger fish to fry right now.
                      "

                      http://roy.gbiv.com/untangled/2008/paper-tigers-and-hidden-dragons

                      Saying "Here's my data format, use HTTP" is not the same thing as a
                      hypertext API which either re-uses or creates media types which
                      delineate generic operations. Roy is clearly saying that having some
                      collection of GIF images (be they sparse-bit arrays or pictures of your
                      dog playing frisbee) you can interact with using GET, PUT and DELETE
                      and the http:// URI scheme (i.e. "see RFC2616") is RPC, _not_ REST.

                      A Uniform REST Interface has a generic "retrieval operation" which maps
                      to "GET" in HTTP, "RECV" in FTP etc. This operation may also be
                      referred to as "dereferencing a resource." So a REST API's methods are
                      a function of whatever protocols are specified by its resources' URI
                      schemes. In REST, an API can remain static as protocols evolve -- the
                      waka protocol and the HTTP protocol would accomplish exactly the same
                      thing, using different syntax, with waka presumably offering better
                      caching and pipelining that works, but serving the same representations
                      (except that URIs will vary by scheme); they can even run in parallel.

                      In a RESTful Atom Protocol system, the media type specifies HTTP, not
                      FTP, therefore the generic retrieval operation maps to HTTP GET. The
                      decision to restrict Atom Protocol operations to HTTP was deliberate
                      and reasoned. Whereas HTML 4.01's form definition is an example of a
                      REST mismatch -- I would correct it as follows:

                      "
                      retrieve: Using the 'retrieval' method, the form data set is appended
                      to the URI specified by the action attribute (with a question-mark
                      ("?") as separator) and this new URI is sent to the processing agent.

                      submit: Using the 'submission' method, the form data set is appended
                      to the URI, or sent in the body of the request, and sent to the
                      processing agent.

                      remove: Using the 'removal' method, the URI specified by the action
                      attribute is removed by the processing agent.
                      "

                      This wording is more deferential to the nature of the URI and media
                      type chosen. The text/html media type (HTML 5 is WIP so I don't
                      include it yet) doesn't restrict itself to the HTTP protocol anywhere
                      else, forms shouldn't have either. I would also change the wording
                      such that application/x-www-form-urlencoded could be used with any
                      method/operation. I would alter the wording on idempotency to defer to
                      the protocol method used on submission operations.

                      My way, the HTML coder can use 'retrieve' plus 'application/x-www-form-
                      urlencoded' to instruct user agents to append specifically-formatted
                      name-value-pair ASCII text to a target URI of any protocol scheme. The
                      over-the-wire method used is determined by the user agent (i.e. GET for
                      HTTP, RECV for FTP) depending on the combination of protocol and media
                      type.

                      HTML coders could instruct user agents to PUT by using 'submit' and a
                      media type that isn't application/x-www-form-urlencoded or multipart/
                      form-data, both of which would signal the user agent to POST, assuming
                      HTTP URIs (Atom content may be POSTed within multipart/form-data to
                      maintain some semblance of Atom Protocol). PATCH is a possible result,
                      given a delta-only media type (someone really should define one for
                      name-value pairs).

                      Other URI schemes would yield different results, for example there's no
                      POST in FTP, but there's also no reason one couldn't RECV from an FTP
                      URI using application/x-www-form-urlencoded (a media type identifier
                      not meant to go over the wire) to instruct the user agent how to format
                      the request (same w/ DELETE). An FTP request to PUT either media type
                      would be possible, too.

                      Such a re-wording of HTML 4.01 would not only remove the REST mismatch,
                      but also describe how most browsers work in practice with GET and POST
                      form methods ('get' and 'post' values for @method would be deprecated,
                      but not removed, by my proposal) using schemes other than http:, as well
                      as those oddball user agents which allow 'put' as an HTML 4.01 form
                      @method.

                      This rather long example (do I write any other kind) illustrates proper
                      RESTful media type design, by showing how some minor changes to HTML
                      4.01 would result in the text/html media type being capable of
                      providing a hypertext REST API for an Atom Protocol-ish system without
                      resorting to scripting, invalid markup or major (HTML 5, Xforms)
                      rethinking of forms.

                      The key takeaway here, is I've just designed an extension to HTML 4.01
                      and the text/html media type identifier. All it does is define three
                      generic operations for use in @method and specify their behavior in
                      combination with standard media types. I'll probably flesh it out as a
                      standalone document, come to think of it. This extension to text/html
                      may be supported natively within browsers, or implemented using XHR
                      code-on-demand to extend the browser's knowledge of text/html to
                      encompass the extension.

                      I do not need to reference generic or protocol-specific methods,
                      explaining that one combination yields PUT and another yields POST when
                      the protocol is HTTP, or that retrieval operations follow HTTP GET --
                      this common-knowledge coupling is contained within the definitions of
                      the protocols identified by the URI scheme. For the same reason, you
                      can't say "see RFC2616" to define form action methods, because this
                      doesn't instruct the client what to do if the URI scheme is mailto:.

                      The media type of whatever hypertext is driving a REST API doesn't
                      redefine or override method definitions (although media types may
                      define new methods). Nor, as Roy has said, can it "bind a service to
                      do anything -- it only serves as a guide for interpretation of the
                      current state." So REST requires a forms language capable of
                      instructing the client how to change state according to the underlying
                      API (the hypertext constraint), such that client-side assumptions,
                      guessing and sniffing don't factor in.

                      http://www.imc.org/atom-protocol/mail-archive/msg11487.html

                      In order for JSON to be such a forms language, it can't bind a service
                      to behave as a WebDAV fileserver by saying "see HTTP" (granted, you've
                      said "see RFC2616" but that's even more restrictive by saying I can't
                      use MGET, etc.), it must instead serve as a guide for the user agent to
                      interpret responses.

                      When a browser encounters a form with method GET and media type
                      application/x-www-form-urlencoded, if all the browser developer had to
                      go on was "see RFC2616" then a GET would be made to the target URI,
                      with an urlencoded entity-body and a Content-Type header. Which, of
                      course, is nonsensical -- the media type simply instructs the client
                      how to format the URL for the GET request (which certainly isn't
                      apparent from reading RFC2616 to determine how to handle this action).

                      The text/html media type instructs the client how to convert form
                      fields into name-value pairs. The application/x-www-urlencoded media
                      type instructs the client how to encode the name-value pairs into a URI
                      query segment. If and only if the protocol is HTTP, does RFC2616 come
                      into play, defining how to send the prepared query URI to the server as
                      a properly-formatted GET request and interpret the response code.

                      So I really can't emphasize strongly enough that just plugging HTTP
                      methods into a form and relying on the client's inherent knowledge of
                      HTTP to guess what to do, falls short of what's needed for hypertext
                      REST API development. That your particular project is JSON doesn't
                      matter. Any markup language can potentially be made into a hypertext
                      media type.

                      But the only way such a media type is useful in REST is if it
                      delineates the behavior of generic operations, and provides enough
                      structure to distinguish the variant purposes of different URIs and
                      different media types. Some URIs instruct clients how to interpret
                      representations (XML namespaces) and aren't meant for dereferencing,
                      just as some media type identifiers are meant to be transmitted as
                      headers, while others are meant as hypertext instructions to the user
                      agent (format these name-value pairs as a URI query string).

                      >
                      > >> Discovery of POST actions is completely different than PUT (since
                      > >> PUT's behavior is implied by a GET response). A JSON Schema can
                      > >> describe possible POST actions with submission links, including an
                      > >> acceptable content type (in the "enctype" property).
                      > >>
                      > >
                      > > I don't see how. Regardless of schema, there's simply no mention in
                      > > the media type definition of JSON for describing URIs or methods,
                      > > i.e. there's no forms language. The demo I posted consists of
                      > > XHTML steady- states derived from various source representationss
                      > > of other media types. These steady-states (will) provide a
                      > > self-documenting API to the underlying Atom-based system.
                      > >
                      > > The user isn't trying to discover PUT vs. POST actions. The user is
                      > > trying to drive an application to another steady-state. The user
                      > > agent needs to translate that user goal into HTTP interactions. If
                      > > the user is trying to add a new post, the user agent is instructed
                      > > to POST to the domain root. If the user is trying to add a new
                      > > comment, the user agent is instructed to POST to the appropriate
                      > > comment thread. If the user intent is to edit an existing entry,
                      > > the user agent is instructed to PUT to the existing URI. In each
                      > > case, the user agent is instructed to use application/atom+xml;
                      > > type=entry.
                      > >
                      > > There's no RESTful way to instruct any user agent that "this system
                      > > uses Atom Protocol" and this may not be inferred by the fact that
                      > > the system uses Atom. All I can do is provide a self-documenting
                      > > hypertext API which instructs user agents how to interact with the
                      > > system. This API may or may not conform to Atom Protocol. Whether
                      > > it does or not is less important to REST than its presence.
                      > >
                      > > None of this is any different for a system based on JSON rather than
                      > > Atom. As a REST system, I could change my Atom backend to a JSON
                      > > backend on a whim. I'm not saying it would be easy, but I am saying
                      > > that the application states wouldn't change. The HTML would still
                      > > present a textarea, changes to that textarea would be submitted to
                      > > the same URI, using whatever media type the form says to use -- all
                      > > HTML user agents automatically update to the new API.
                      > >
                      > > If you need to guess what media type to use then you can't possibly
                      > > be using REST. A REST API will always tell you exactly what media
                      > > type to use. It isn't implicit in any guessable fashion, it's
                      > > explicit. If it isn't explicit, it isn't REST. HTML says what
                      > > POST does, but only your hypertext can specify media type, if you
                      > > lack such hypertext you lack a critical REST constraint.
                      >
                      > There is certainly nothing wrong with a specifying what media type a
                      > server can handle in the media type definition or hypertext (JSON
                      > Schema allows for specifying an acceptable media type for requests as
                      > well)
                      >

                      What media types are acceptable is hard-coded into the user agent for
                      good reason. This discussion has been had here many times before, that
                      overriding that with something like @type inside <a> in an effort to
                      get a different variant goes against REST. It's playing frisbee with
                      your dog all backwards. In the case of a negotiated resource, if there
                      is need to instruct the client to retrieve a specific variant (override
                      conneg), then assign that variant a URI and send that to the client.

                      Again, REST isn't about performing prefetch optimization, it's about
                      "sending whatever is most likely to be optimal first and then provide
                      a list of alternatives for the client to retrieve if the first response
                      is unsatisfactory." Web architecture is based on the notion that an
                      @type on a link is a hint and only a hint, this goes for JSON too --
                      you can allow for this hint in a schema, but a schema can't make that
                      hint override user agents' hard-coded Accept headers.

                      >
                      > however the dynamic representation/content negotiation
                      > principle implies that a server may have capabilities to handle
                      > various types that may independently evolve. I know my server software
                      > can handle various media types to update resources (JSON, JS, XML,
                      > url-encoded, etc.).
                      >

                      Of course. For any given request, I respond with the interface that's
                      most likely to be optimal, first. An Atom Protocol client will get raw
                      Atom and be able to interoperate with the system somewhat on that level,
                      but the user can always choose the rel='alternate' HTML variant and get
                      features (like PATCH-based social tagging) Atom Protocol clients can't
                      be instructed to use.

                      Or, the client is a browser supporting XForms, so it gets a full-blown
                      REST app that implements Atom Protocol and any additional features
                      (like PATCH-based social tagging). Otherwise, the browser gets an HTML
                      4.01 almost-REST API that doesn't quite implement Atom Protocol (no
                      PUT) or any additional features. User agents may introspect hypertext
                      in the form of HTTP Accept, Allow and Alternates headers, link elements
                      and/or link headers, etc. to determine alternative courses of action to
                      present to the user.

                      Or, the user is presented with the information needed to decide to
                      switch to a user agent with Xforms capability, to enable full
                      interaction with the underlying API. Or, I implement my HTML 4.01
                      forms extension using XHR code-on-demand, providing a full-blown REST
                      API that doesn't exactly follow Atom Protocol but yields the same
                      results and has all the additional features -- in which case I don't
                      care that nobody uses Xforms-enabled browsers or Atom Protocol clients.

                      If a user agent gets the wrong variant, it won't be a fatal error where
                      the user agent can't interact with the site. A non-xforms browser
                      can't possibly be triggered to use Xforms (this isn't a conneg issue),
                      a browser can't possibly get the raw Atom unless linked to it
                      explicitly, and the worst that can happen is a non-js browser will only
                      be able to use GET and POST (not-quite-REST as PUT is tunneled over
                      POST in such cases, not-quite-Atom Protocol because Atom is wrapped in
                      multipart/form-data). Standard graceful degradation, this.

                      So I don't understand what problem you're trying to solve by trying to
                      figure that all out _before_ receiving an initial representation. It's
                      a Sisyphean task -- by the time some third party figures out how to do
                      that for my system, I've changed the interfaces and their client breaks,
                      whereas if they'd have followed my hypertext their client would have
                      just self-updated. The same would go for any REST system, there's
                      simply no need to train your dog to throw the frisbee, or define media
                      types to support it.

                      Using @type on links in HTML is only meant as a hint, because some
                      resources are negotiated. Where resources aren't negotiated, there's
                      no excuse for this hint to be wrong (I call those unflagged 500 errors).
                      Its presence allows HTML code to be considered a self-documenting API.
                      Without that hint, the resource must be dereferenced to determine its
                      nature. That's self-descriptive messaging, but without @type inside
                      HTML (or such provision in some other markup language) there's no way
                      to self-document the API in application steady-states.

                      Under no circumstances is hypertext allowed to change the browser's
                      Accept header. This is a case where the real world is actually within
                      REST's constraints (layered system, in this case), I can't think of a
                      situation where a server is allowed to dictate to a client what media
                      type that client should Accept. I know the Javascript community would
                      like to do away with this, but I'm afraid it's a fundamental aspect of
                      Web architecture to which the "if it ain't broke, don't fix it" rule
                      must apply.

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