Filters, related resources and inflection


#1

Hi there,

I’m considering using JSON API in my next project and as I was reading through specs and recommendations, I came across issues I’d like to nitpick and talk about. To my delight JSON API is pretty much spot on WRT what I need. So no XKCD standard+1 is going to happen. Pure joy… :slight_smile:

(1) Filters, pagination, sparse fieldsets.

RFC3986 states that gen-delims - in case of filters characters [ and ] - should be escaped in the URL. So I guess my comment is that using [] in query should be discouraged altogether (even if specs use them mostly for readability, as stated in one of the pagination notes).

Do you have any opinion on this matter? Any alternative schemes people are employing for filters? Sparse fieldsets are probably lost cause as per “this standard is incremental” but I really, really would like to understand why people insist on using [] where () - unreserved in the query portion of the URI - would work just as nicely. :expressionless:

I’d also like to see specs state explicitly whether URLs should be pre-escaped or not, i.e. should JSON contain { "src": "http://example.com/comments?filter[post]=1" } or { "src": "http://example.com/comments?filter%5Bpost%5D=1" }, Alternatively it could be unopinionated, but I like strong rules. :wink:

(2) Inflection in filters and other places.

This looks like a typo/omission but filter parameters are singular in the examples provided in the recommendation. This contradicts with specs’ “value (…) can be either plural or singular; (…) the same value should be used consistently throughout an implementation” note and plurals used everywhere throughout spec/recommendations. IMO ‘post’ and ‘author’ should become ‘posts’ and ‘authors’ so that vocabulary used in spec and recommendation is consistent.

Or perhaps it’s not a mistake and relationships/related resources should be addressed using vocabulary separate from one that’s used for resource identification? What I mean by that is that even though author (singular) comes from a set of people (plural), resource referenced through a relationship should reflect multiplicity (arity? don’t know what the right word is…) of the relationship and not follow the number used for resources. Thoughts?

(3) Related resources.

This is more of a philosophical issue I guess. Let’s say we have a blog with one author (id:3) and one post (id:7) and relationship between posts and authors is always 1:1. This post advertises related resource through /posts/3/authors, which in turn returns resource representing our one and only author. My issue is that basically this URL represents the same data /authors/7 does and latter could/should be considered a canonical address of the resource.

I understand that canonical address would/should appear in included/type:people but I’m wondering whether contents of the /posts/3/authors and /authors/7 responses should be the same. If yes, shouldn’t /posts/3/authors redirect to the canonical URL?

I know this is pity detail but I somehow care about those things. :sweat: Thanks for the time you took reading.

-Dom


#2

In your particular example they might well be (apart from the top level self link), but there’s no requirement that they must be.
In other scenarios there might easily be different responses. Consider the case where a blog is allowed to have multiple authors; /posts/3/authors would return details of multiple authors but /authors/7 would only return details of one. Or an API modelling data that changes over time, /films/highestGrossing would always exist but could return details of /films/23541 today and of /films/67890 tomorrow

There’s no need for it to do this via a redirect though. What’s wrong with the following URLs all (directly) returning the same data?: /people/ddalek, /people/motherOfDDALEK/firstChild, /people/fatherOfDDALEK/firstChild, /people/sisterOfDDALEK/oldestBrother, /people/sisterOfDDALEK/oldestSibling, /people/husbandOfDDALEK/spouse Although they all happen to refer to the same entity, they are all different concepts (hence different URLs). Why “disguise” a concept relevant to the client by forcing (via redirect) the client to access the data via a canonical URL? (The client can always get the canonical URL from the resource’s self link if it wants to know it.)