Hypermedia link template - need to replace query parameters

[Tony]

Hi,

I'm creating a hypermedia API which is generally working really well for us, but there's one use case that I'm struggling with.  

This section of the API is providing functionality to browse a catalogue of things, in this case there is a hierarchy of categories which a client can navigate providing filters on the set things in the category (basically the common features you'd expect browsing any large catalogue).  To do this we provide a "Category" resource with a HAL hypermedia link to the "items" related to that category.  This works really well as there are quite a lot of editorially controlled options for presenting the set of items related to a category and now all this is hidden behind the link - great.

We also have a requirement for the client to be able to present additional filter and sort options within the set of items related to the category.  This is handled by templating the items link to allow the client to supply the appropriate filter / sort query parameters e.g.

_links : {

"items" : { "href" : "/items?somehiddenFilter=somevalue{&filter,sort}"}

}

Again this works well, allowing the client to control the subset of filtering it needs to know about and hiding the rest.

However the problem is that different Categories should have different default sort order (e.g. some list items alphabetically and some by date).  Initially this looked easy, simply add the appropriate sort parameter in the link and it all works.  

_links : {

"items" : { "href" : "/items?somehiddenFilter=somevalue&sort=date{&filter,sort}"}

}

However now when the client tries to override the sort we end up with two sort parameters and the server can't know which to respect.

Expanded link to sort by alpha: 

/items?somehiddenFilter=somevalue&sort=date&sort=alpha

So the question is how to allow a link to supply a default parameter value and also allow a client to override it.  Currently we have two options:

1) We could document the API to say that the sort parameter should first be stripped from the URL and then the template applied, but this feels a bit hacky.

2) We could add a "defaultSort" or other named parameter for the default value, but again this "feels" wrong

Any other options I'm missing, or reasons for or against the options above?

Thanks,

Tony

[Jørn Wildt]

I just checked the URI template RFC (https://tools.ietf.org/html/rfc6570) - and I cannot find a thing about default values which could have solved the problem ... I had hoped to be able to write something like "/items?somehiddenFilter=somevalue{&filter,sort=date}".

I would go with option (2) which illustrates nicely how URI templates can be used to change URI structures depending on obscure server details *without* breaking existing clients :-)

/Jørn

--
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.

[Pete Johanson]

If a certain category has a default sort, why not simply apply that default sort when the 'sort' parameter is not provided? You can keep the original URI template, and clients know that omitting that parameter will result in the natural sort for a given category. Alternately, if omitted, you could return a HTTP redirect to the URL with the default sort parameter supplied.

-pete

[Tony]

Hi Pete,

The issue is that we have one endpoint for listing the items which supports several different types of sort but it is the category that defines what the default should be.  So for example:

category a) "Best Sellers" would have a link "/items?sort=popular"

category b) "New Items" would have a link "/items?sort=date"

category c) "Editors Choice" would have a link "items?sort=rank"

... there are several other use cases / sort options to consider as well ...

In all cases the client should be able to sort the items in another sort order - hence need to override the default sort order.

Hi Jørn,

I also went through the RFC hoping to find something, but sadly not.

I think we might have to go down the "defaultSort" parameter option.  Whilst hidden from the client perspective, it's going to look odd for the server to have two parameters that both affect the sort order.  Was hoping I was missing something more elegant.

 

Tony

[Michael Tiller]

Couldn't you make the category (e.g., "Best Sellers") return an array of links where you actually enumerate all the possibilities but use the default to determine the ordering?  That way, you actually aren't using URI templates at all, just arrays of links.  It allows you to control the ordering on a per category basis.

--

Mike