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

Good way to report types of a resource?

Expand Messages
  • skillzero
    I have a resource /players where you can POST to create a new player /players/{id}, but I also want a way to report the supported types of players. I m
    Message 1 of 10 , Nov 3, 2010
    • 0 Attachment
      I have a resource /players where you can POST to create a new player /players/{id}, but I also want a way to report the supported types of players. I'm struggling with the correct, RESTful way to do that. Here's the ways I've thought of and they all seem to have problems:

      1. /players/types. This seems the closest to other things I've seen out there (e.g. atom categories), but it looks weird to me because I expect /players/{id}, but "types" isn't really an id.

      2. /players/{id}/types. This seems okay if you already have an id, but since players are created dynamically, the client won't know the id beforehand. And you need to know the type of player to create one. Additionally, the types supported by a specific player instance may mean something else (e.g. it could mean the types its compatible rather than types you can create).

      3. /player-types. This seems a little ugly to me, but maybe it's fine?

      Is there a good way to do this?
    • Ray
      So...the entity you POST to /players has a type field? ...and that field is limited to a discrete set of values? If yes to both of the above, I think
      Message 2 of 10 , Nov 3, 2010
      • 0 Attachment
        So...the entity you POST to /players has a "type" field? ...and that field is limited to a discrete set of values?

        If yes to both of the above, I think someone that posts here regularly ( =D ) would say to give your players entity a type and register that type with IANA. If a person who wanted to create players then had the serendipity to come across your API, they would know exactly where to find documentation on your new type.

        The above is probably the most RESTful.

        Other approaches include:

        1) create a resource catalog that provides type information for all entities in your system

        2) something similar to your suggestions - /players/types

        3) this one is a little more involved....
        so, in theory, the /players resource could respond to a GET request with some hypermedia containing links and/or representations of all known players. Ideally, you'd like to be able to filter those players. You could add query parameters that control:

        a) pagination
        b) search - the fabulous q= from open search
        c) what we called projections - filtering the fields of the entities
        d) ...or some query parameter that would return type information

        However, all of these other approaches violate the uniform interface constraint to some degree. Users must somehow discover how to parse the resource catalog, how to add a trailing /types or how to add a types query parameter.


        --- In rest-discuss@yahoogroups.com, "skillzero" <skillzero@...> wrote:
        >
        > I have a resource /players where you can POST to create a new player /players/{id}, but I also want a way to report the supported types of players. I'm struggling with the correct, RESTful way to do that. Here's the ways I've thought of and they all seem to have problems:
        >
        > 1. /players/types. This seems the closest to other things I've seen out there (e.g. atom categories), but it looks weird to me because I expect /players/{id}, but "types" isn't really an id.
        >
        > 2. /players/{id}/types. This seems okay if you already have an id, but since players are created dynamically, the client won't know the id beforehand. And you need to know the type of player to create one. Additionally, the types supported by a specific player instance may mean something else (e.g. it could mean the types its compatible rather than types you can create).
        >
        > 3. /player-types. This seems a little ugly to me, but maybe it's fine?
        >
        > Is there a good way to do this?
        >
      • Eric J. Bowman
        ... Actually, I d recommend using (X)HTML, this sounds like a resource- type issue, not a media-type issue. ... The constraint you re looking for is the
        Message 3 of 10 , Nov 3, 2010
        • 0 Attachment
          "Ray" wrote:
          >
          > If yes to both of the above, I think someone that posts here
          > regularly ( =D ) would say to give your players entity a type and
          > register that type with IANA.
          >

          Actually, I'd recommend using (X)HTML, this sounds like a resource-
          type issue, not a media-type issue.

          "skillzero" <skillzero@...> wrote:
          >
          > And you need to know the type of player to create one.
          >

          The constraint you're looking for is the hypertext constraint. GET
          some HTML from /players containing a form, with a selection control
          listing the allowed types. POST that form to /players to create
          /players/{id}. REST isn't about what your URLs look like, that's a
          matter of preference, not constraint.

          -Eric
        • Ray
          ... Sorry. I thought you were on board the resource type & media type crunched into one field approach.
          Message 4 of 10 , Nov 3, 2010
          • 0 Attachment
            --- In rest-discuss@yahoogroups.com, "Eric J. Bowman" <eric@...> wrote:
            >
            > "Ray" wrote:
            > >
            > > If yes to both of the above, I think someone that posts here
            > > regularly ( =D ) would say to give your players entity a type and
            > > register that type with IANA.
            > >
            >
            > Actually, I'd recommend using (X)HTML, this sounds like a resource-
            > type issue, not a media-type issue.
            >
            > <snip/>
            >
            > -Eric
            >

            Sorry. I thought you were on board the "resource type & media type crunched into one field" approach.
          • Eric J. Bowman
            ... When I talk about resource type, I m talking about an abstraction which manifests itself in various ways in my system (hypertext, configuration files), but
            Message 5 of 10 , Nov 3, 2010
            • 0 Attachment
              "Ray" wrote:
              >
              > Sorry. I thought you were on board the "resource type & media type
              > crunched into one field" approach.
              >

              When I talk about resource type, I'm talking about an abstraction which
              manifests itself in various ways in my system (hypertext, configuration
              files), but never in a header or any other field. I have over a dozen
              resource types on the system I'm developing, all of which negotiate
              between the same handful of ubiquitous media types. Media types
              identify generic processing models for families of forwards-backwards
              compatible data types.

              The application logic is in the interpretation of the payloads, after
              following the designated processing models. The application code has
              knowledge of the resource type, the user-agent requires none, i.e. this
              is not a concern at the protocol layer.

              If I were negotiating a dozen resource types over separate handfuls of
              custom media types, I'd have complexity and interoperability issues. I
              also have resource types (e.g. images, scripts) which are bound to a
              single media type. Currently there are 11 ubiquitous media types on my
              system, one opaque string masquerading as a media type, and application/
              x-www-form-urlencoded.

              -Eric
            • Erlend Hamnaberg
              One way to do this could be do this: The /players/types is discovered from somewhere. GET /players/types One possible response could then be: 300 Multiple
              Message 6 of 10 , Nov 4, 2010
              • 0 Attachment
                One way to do this could be do this:

                The /players/types is discovered from somewhere.

                GET /players/types

                One possible response could then be:

                300 Multiple Choices
                Content-Type: application/xhtml+xml
                <ul>
                 <li><a href="/players/types/one" rel="http://rels.example.com/player-create"></a></li>
                 ...
                </ul>

                This resource could then give a HTML form which then contains the type pre-filled, and the rest of the information ready to be added.
                You could look at this as a player template.

                The form's action is then POSTed back to some resource, e.g /players which then accepts the application/
                x-www-form-urlencoded request.


                The response could then be:

                201 Created
                Location: http://example.com/players/1



                --

                Erlend

                On Wed, Nov 3, 2010 at 10:44 PM, skillzero <skillzero@...> wrote:
                 

                I have a resource /players where you can POST to create a new player /players/{id}, but I also want a way to report the supported types of players. I'm struggling with the correct, RESTful way to do that. Here's the ways I've thought of and they all seem to have problems:

                1. /players/types. This seems the closest to other things I've seen out there (e.g. atom categories), but it looks weird to me because I expect /players/{id}, but "types" isn't really an id.

                2. /players/{id}/types. This seems okay if you already have an id, but since players are created dynamically, the client won't know the id beforehand. And you need to know the type of player to create one. Additionally, the types supported by a specific player instance may mean something else (e.g. it could mean the types its compatible rather than types you can create).

                3. /player-types. This seems a little ugly to me, but maybe it's fine?

                Is there a good way to do this?


              • Erik Mogensen
                ... You have a dozen or so resource types (e.g. person, order or whatever; I don t know your domain) and they all typically have an XHTML representation, and
                Message 7 of 10 , Nov 4, 2010
                • 0 Attachment
                  On Thu, Nov 4, 2010 at 6:13 AM, Eric J. Bowman <eric@...> wrote:
                   

                  When I talk about resource type, I'm talking about an abstraction which
                  manifests itself in various ways in my system (hypertext, configuration
                  files), but never in a header or any other field. I have over a dozen
                  resource types on the system I'm developing, all of which negotiate
                  between the same handful of ubiquitous media types. Media types
                  identify generic processing models for families of forwards-backwards
                  compatible data types.

                  You have a dozen or so resource types (e.g. person, order or whatever; I don't know your domain) and they all typically have an XHTML representation, and perhaps a url encoded form representation (and some of the other 11 ubiquitous media types) of some sort.

                  Is that a correct assumption?

                  If it is, then I assume that your resources work perfectly in Firefox or any other generic user agent, and can be cached and transmogrified using Google's mobile proxy and so on.  Nice.

                   
                  The application logic is in the interpretation of the payloads, after
                  following the designated processing models. The application code has
                  knowledge of the resource type, the user-agent requires none, i.e. this
                  is not a concern at the protocol layer.


                  Here's where I'm not 100% clear on your terminology.  Normally, I'd interpret "application logic" as the server component, but here I'm inclined to understand it as a rich client component, since it does most of the "interpretation of the payloads".

                  If I'm right to interpret "application logic" as a client connector, then that more specific client (e.g. yours) would recognize the "person HTML" as a person resource type and (perhaps?) present that differently... Or...?  You mention that the application logic knows about resource types, so I'm curious to understand how it recognizes them.

                  And lastly, just a word of praise :-)  I greatly appreciate your efforts in this list, and although I've been learning REST for 7 years, I still think there's more to it:


                • William Martinez Pomares
                  Hello ... I totally agree with Erick on this. All the confusion comes precisely with the URL templating approach, which is fine but I do not favor much. Do not
                  Message 8 of 10 , Nov 4, 2010
                  • 0 Attachment
                    Hello
                    --- In rest-discuss@yahoogroups.com, "Eric J. Bowman" <eric@...> wrote:
                    >
                    > REST isn't about what your URLs look like, that's a
                    > matter of preference, not constraint.

                    I totally agree with Erick on this.
                    All the confusion comes precisely with the URL templating approach, which is fine but I do not favor much.

                    Do not think on URIs. They can even be consecutive numbers, who cares. Focus on what you are requesting, the resources.
                    You have, it seems, several resources there.
                    1. One that is a "container" of players. You may not need that one, as the players may be grouped by a field or something. For now, you have it.
                    2. The player itself.
                    3. A player's type list, which contains the player types. I guess those are just a value in for a field. It may even be something more complex, like a format (e.g. each player type may have a different format).

                    So, as you have three resources, think then you will need three different URIs. Those may be ugly or not, who cares, what it is important is to have access to all those from a starting point.

                    Following the suggestion Erick provides, will not only eliminate the type list from being a resource, but also simplify the interaction, as you won't need to request the type first in order to create the player.

                    Cheers.
                  • Eric J. Bowman
                    ... Thanks. The nature of the hypertext control is what establishes the relationship, i.e. whether a player can be created with multiple types, or what
                    Message 9 of 10 , Nov 5, 2010
                    • 0 Attachment
                      "William Martinez Pomares" wrote:
                      >
                      > Following the suggestion Eric provides, will not only eliminate the
                      > type list from being a resource, but also simplify the interaction,
                      > as you won't need to request the type first in order to create the
                      > player.
                      >

                      Thanks. The nature of the hypertext control is what establishes the
                      relationship, i.e. whether a player can be created with multiple types,
                      or what combinations of types aren't allowed. This is what's meant by
                      a self-documenting API.

                      -Eric
                    • Eric J. Bowman
                      ... Close. The negotiated representation may be application/xhtml+xml, application/xml, text/html, text/xml, text/plain or application/atom+ xml (sometimes ;
                      Message 10 of 10 , Nov 5, 2010
                      • 0 Attachment
                        Erik Mogensen wrote:
                        >
                        > >
                        > > When I talk about resource type, I'm talking about an abstraction
                        > > which manifests itself in various ways in my system (hypertext,
                        > > configuration files), but never in a header or any other field. I
                        > > have over a dozen resource types on the system I'm developing, all
                        > > of which negotiate between the same handful of ubiquitous media
                        > > types. Media types identify generic processing models for families
                        > > of forwards-backwards compatible data types.
                        > >
                        >
                        > You have a dozen or so resource types (e.g. person, order or
                        > whatever; I don't know your domain) and they all typically have an
                        > XHTML representation, and perhaps a url encoded form representation
                        > (and some of the other 11 ubiquitous media types) of some sort.
                        >
                        > Is that a correct assumption?
                        >

                        Close. The negotiated representation may be application/xhtml+xml,
                        application/xml, text/html, text/xml, text/plain or application/atom+
                        xml (sometimes ; type=feed). My resource types are related to the
                        integration of wiki, weblog and forum; all of which are represented as
                        either Atom Entry or Atom Feed documents. Atom (etc.) is encapsulated
                        by HTML to provide a hypertext user interface. The HTML user interface
                        is negotiated based on client capability (read on), and it's this user
                        interface which communicates the difference in resource types to the
                        user (read on).

                        >
                        > If it is, then I assume that your resources work perfectly in Firefox
                        > or any other generic user agent, and can be cached and transmogrified
                        > using Google's mobile proxy and so on. Nice.
                        >

                        Almost. I'm using client-side XSLT, initiated via XML PI. Most user-
                        agents grok application/xhtml+xml, but IE needs application/xml while
                        Atom-only clients are redirected to application/atom+xml. Other user-
                        agents need a text/html represenation, generated server-side; text/xml
                        and text/plain are really just there to demonstrate how certain browsers
                        fail to respect sender intent. In a perfect world, I wouldn't need
                        conneg, if all user-agents (bots, browsers etc.) would only agree to
                        support XSLT via XML PI using application/xhtml+xml, because that media
                        type best describes sender intent (so does text/html for my server-side
                        XSLT, but in my case application/xml and text/xml do not because current
                        browsers don't respect that intent, and text/plain only does for user-
                        agents which respect my display-rather-than-render intent).

                        IOW, my resources *should* work perfectly as you say, without conneg.
                        The fact that conneg exists, is what allows interoperability of new
                        approaches, i.e. browser-resident XSLT, and compensates for the fact
                        that in the real world not every participant in the communication is
                        well-behaved. Minting new data/media types for every resource type
                        means your resources fail hard, instead of degrading gracefully. What
                        conneg does for me, is enable graceful degradation and forwards
                        compatibility which is only possible when resource type is decoupled
                        from media type.

                        >
                        > >
                        > > The application logic is in the interpretation of the payloads,
                        > > after following the designated processing models. The application
                        > > code has knowledge of the resource type, the user-agent requires
                        > > none, i.e. this is not a concern at the protocol layer.
                        > >
                        >
                        > Here's where I'm not 100% clear on your terminology. Normally, I'd
                        > interpret "application logic" as the server component, but here I'm
                        > inclined to understand it as a rich client component, since it does
                        > most of the "interpretation of the payloads".
                        >
                        > If I'm right to interpret "application logic" as a client connector,
                        >

                        In REST, the application logic is what executes in client components.
                        Typically, application logic also resides in the server code generating
                        the code executing in client components, however, I've used client-side
                        XSLT to place it entirely within the browser. So my terminology was
                        confusing, as I was thinking in terms of my system. What I meant was,
                        the API is in the interpretation of payloads. This is the notion of a
                        self-documenting API, which my HTML served as text/plain should never
                        be, but which IE transforms anyway, by treating it as application/xml,
                        which isn't my intent either; or what IE does, which ultimately amounts
                        to treating it as text/html, which is a privilege escalation.

                        What media type to send shouldn't be considered part of the application
                        logic; it's system logic on the origin server. My application logic is
                        expressed by the combination of HTML, XSLT, Javascript, CSS, images,
                        Atom Entry/Feed/Category, and XBEL documents which together comprise the
                        steady-states which users interact with; processed according to the
                        media types and encodings I've assigned to them per-request on the basis
                        of capabilities and realities. Resource type is key to the rendering
                        and interpretation of the API, yet bears no relation to the processing
                        rules used to decode that API into, say, a DOM.

                        >
                        > then that more specific client (e.g. yours) would recognize the
                        > "person HTML" as a person resource type and (perhaps?) present that
                        > differently... Or...? You mention that the application logic knows
                        > about resource types, so I'm curious to understand how it recognizes
                        > them.
                        >

                        The system I'm working on uses Atom Feeds to represent many resource
                        types -- one is wiki page, another is weblog archive. The HTML
                        interface of a wiki page is different than that of a weblog archive.
                        Neither the application logic nor the user-agent cares about this
                        distinction -- the interface is uniform -- they just need to call the
                        proper transformation.

                        So the distinction between resource types on my system, manifests
                        itself in the @href of the xml-stylesheet PI. It's incidental, and not
                        a thing to standardize as separate media types or present as custom link
                        relations. The user sees either what looks and functions like a wiki
                        page, or what looks and functions like a weblog archive (regardless of
                        whether by user I mean human or machine).

                        The users know what their goals are, the hypertext explains how to
                        accomplish those goals; user-agents provide a mechanism which translates
                        these goals into actions. This mechanism (hypertext over HTTP) simply
                        doesn't need to care about resource types. This decoupling is what
                        allows my representations to be negotiated between media types. If the
                        mechanism needs to know about resource type, it's coupling client to
                        server.

                        Who cares about resource type, are resource owners and end users.
                        "Wiki page" and "weblog archive" are abstract notions the resource
                        owner needs to communicate to the end user. This understanding has no
                        bearing on the semantics of the messaging between connectors, where
                        everything is an Atom Feed or Entry, and roughly follows Atom Protocol.
                        The application logic, client-side or server-side, makes sure that the
                        right markup goes to the right place, without caring about resource
                        type -- media types aren't contracts, just a shared understanding of
                        common processing models.

                        >
                        > And lastly, just a word of praise :-) I greatly appreciate your
                        > efforts in this list, and although I've been learning REST for 7
                        > years, I still think there's more to it:
                        >
                        > http://stackoverflow.com/questions/3543075/what-is-a-concise-way-of-understanding-restful-and-its-implications/3543326#3543326
                        >

                        Or, a lot less to it. Thanks, btw, and sorry you're having difficulties
                        with rest-discuss (happens). The most concise explanation of REST I
                        can give, uses OOP terminology. Resources are objects with IDs. Each
                        object may have one or more methods from a set, which remains uniform
                        from one object to the next, and from one system to the next. If you
                        need more methods, REST says try using more objects, first. Messaging
                        between objects is HTTP.

                        Properties vary depending on the nature of the request (method,
                        selection headers, cache-control), organized by response code. For any
                        response code, each object may have one or more associated data types
                        from a standardized set, the processing of which is determined by a
                        registered set of media types; both of which remain uniform from one
                        object to the next, and from one system to the next. If you need more
                        data/media types, REST says try less coupling, first. The API is
                        described using standardized hypermedia data types and link relations.
                        Hyperlinks are used within properties, to reference other objects for
                        encapsulation, inheritance or extension.

                        Familiar approaches to networked software development (DCOM, CORBA, SOA,
                        many unRESTful HTTP APIs, etc.) attempt to distribute the object over
                        the wire, ignoring the constraints imposed by the network (see REST 2.1,
                        2.3.1). REST deviates radically from these unproven approaches, by
                        providing a uniform object interface which compensates for the reality
                        of these network constraints by becoming part of the network itself.

                        You aren't distributing your objects, you're attaching them as nodes on
                        a network-based, distributed object messaging bus. Instead of the
                        limited scale of ESB, think GSB -- Global Service Bus, or distributed
                        ESB. You're extending your object *interface* across organizational
                        boundaries, in a proven, standardized fashion described as a set of
                        design constraints named REST (or CREST, or ARRESTED, or whatever set
                        of constraints is appropriate to both the characteristics of the global
                        Internet and the needs of your system). If your object interfaces are
                        application-specific, you're distributing your objects instead of
                        distributing your uniform object interfaces, even with HTTP + URI.

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