Ordering

[blakechambers]

Ordering

While json api does support sorting, it's version is more specific to providing something flexible for all types of sorting and ordering.

While this is nice, in a production system (and certainly for public apis) locking down the ordering to some named that can be managed server-side is a little more realistic. This becomes more important when using named indices in the database, especially with larger datasets.

That said, we should consider a lighter weight ordering syntax, that can match 1-to-1 with any indexed sets you want to provide.

Here's an example syntax of what's being proposed:

class Article
  include Mongoid::Document
  include Mongoid::Timestamps

  field :title
  field :number_of_comments

  belongs_to :author
end

class ArticlesController < ApplicationController
  include Matterhorn::Ordering

  allow_order 'oldest', :created_at.asc
  allow_order 'recent', :created_at.desc

  # first ordered by number_of_comments, then created_at
  allow_order 'most_comments', :number_of_comments.desc, :created_at.desc

  default_order 'oldest'
end

Controller methods

• allow_order - creates a named order. In the above example should pass directly to mongoids sorting on collections. Reserve the keyword 'none', in the future we can add order=none to override default_order
• default_order - specifies which order will be chosen when the order param is not requested

Serialization

Order should be merged into the request env and passed down the chain until it gets interpreted during serialization.

Links

When using ordering, Links should be added for the different named orders. For example, the above controller should add links as such:

GET /articles.json

{
  "orders": {
    "oldest" : "http://example.org/articles?order=oldest",
    "recent" : "http://example.org/articles?order=recent",
  },
  ...

This should allow sorting to be implemented and used alongside ordering in future versions.

[blakechambers]

closed by #56