Patterns for collection handling

[Michael Tiller]

All,

  I recently had a conversation with Mike Amundsen and he, rightfully, suggested moving it here to get a wider range of opinions.

  I'm creating a hypermedia API and I was wondering about patterns and/or best-practices.

  Specifically, let's say I have a resource that represents a collection.  Let's further assume that I'm using a media type like Collection+JSON where you have a notion of queries (and not just links to resources).

  Imagine I have somehow navigated my way to a collection at the URI "/library".  This is just a simple GET with no query string.  Let's imagine that the collection itself provides the following Collection+JSON queries:

"queries" :
  [
    {
      "href" : "/library",
      "rel" : "search",
      "prompt" : "Search by ISBN number",
      "data" :
      [
        {"name" : "isbn", "value" : ""}
      ]
    }, {

      "href" : "/library?listAll",
      "rel" : "items",
      "prompt" : "List all books"
    },

  ]

  Note the URI in the search query is the same as my resource but it specifies a specific query parameter as well.  The other query doesn't take any data but provides a fixed query string to list all items.

  My feeling is that in such a situation, a GET without any query strings should simply return the affordances shown above and not any items.  It should only provide items in the case where it is explicitly queried for them.

  This is both more explicit and more efficient (because it avoids sending a bunch of useless information to the client just so the client can get the affordances it wants to get just the information it wants).

  Do people run into this issue?  If so, is this how you deal with it?  Or is there some other way to approach this?  I would assume even with HAL that you could use relations to do something similar (without needing the "queries" concept from Collection+JSON).

  Comments?

--

Mike

[mca]

you are in control of your own interface. 

if you want to offer a transition that returns only affordances (no data), then do it.  the *way* to do that varies w/ each message design -- and most designs will support more than one way to do it within that single model.

in Cj, i'd likely include a URL in the top "links" collection that looks something like this:

{"rel" : "http://rels.mamund.com/affordances", "href": "...", "prompt" : "Actions"}

note i didn't supply a URL in that example. i don't care which characters you use to construct the URL as long as it returns what is promised.

BTW - if you want to adopt your "convention" of only returning items if there is a query string value, Cj (or any other well-designed format) will not be bothered a bit. in that case, i'd proly include a URL in the "links" collection that returned the item collection (something like this:)

{"rel" : "collection", "href": "...", "prompt" : "Items"}

again, use any URL you wish.

mca

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[Kijana Woodard]

+1 

If you want your API to behave that way, do it.

My advice is to be consistent across resources to reduce "surprise" for consumers.