json_api_server 0.0.1

data/lib/json_api_server/meta_builder.rb

@@ -0,0 +1,39 @@
+module JsonApiServer # :nodoc:
+  # Class for building meta element.
+  # http://jsonapi.org/format/#document-meta
+  #
+  # ==== Example
+  #
+  #  MetaBuilder.new
+  #   .add('copyright', "Copyright 2015 Example Corp.")
+  #   .add('authors', ["Yehuda Katz", "Steve Klabnik", "Dan Gebhardt", "Tyler Kellen"])
+  #   .merge({a: 'something', b: 'something else'})
+  #   .meta  # => { "copyright": "Copyright 2015 Example Corp.",
+  #                  "authors": ["Yehuda Katz", "Steve Klabnik", "Dan Gebhardt", "Tyler Kellen"],
+  #                  a: 'something',
+  #                  b: 'something else'
+  #               }
+  #
+  class MetaBuilder
+    def initialize
+      @hash = {}
+    end
+
+    # Add key and value.
+    def add(key, value)
+      @hash[key] = value
+      self
+    end
+
+    # Push in multiple key/values with merge.
+    def merge(hash)
+      @hash.merge!(hash) if hash.respond_to?(:keys) && hash.any?
+      self
+    end
+
+    # Returns a hash if it has values, nil otherwise.
+    def meta
+      @hash.any? ? @hash : nil
+    end
+  end
+end

data/lib/json_api_server/mime_types.rb

@@ -0,0 +1,21 @@
+#++
+# NOTE: it can cause issues in browsers: https://github.com/json-api/json-api/issues/1048
+# __
+module JsonApiServer # :nodoc:
+  # http://jsonapi.org/format/#introduction -> JSON API requires use of the JSON API
+  # media type (application/vnd.api+json) for exchanging data.
+  #
+  # Include this module in your config/initializers/mime_types.rb
+  #
+  # i.e,:
+  #  # in config/initializers/mime_types.rb
+  #  include JsonApiServer::MimeTypes
+  module MimeTypes
+    api_mime_types = %w[
+      application/vnd.api+json
+      text/x-json
+      application/json
+    ]
+    Mime::Type.register 'application/vnd.api+json', :json, api_mime_types
+  end
+end

data/lib/json_api_server/pagination.rb

@@ -0,0 +1,189 @@
+module JsonApiServer # :nodoc:
+  # === Description
+  #
+  # JSON API Spec: http://jsonapi.org/format/#fetching-pagination - "Pagination links MUST
+  # appear in the links object that corresponds to a collection. To paginate the primary data,
+  # supply pagination links in the top-level links object."
+  #
+  # This class handles pagination. It (1) ensures <tt>page[number]</tt> is a positive integer,
+  # (2) <tt>page[limit]</tt> doesn't exceed a maximum value and (3) generates a pagination sub-query
+  # (to be merged into a master query). It uses the WillPaginate gem
+  # https://rubygems.org/gems/will_paginate/versions/3.1.6.
+  #
+  # === Usage:
+  #
+  # A paginating request will look like:
+  #   /comments?page[number]=1&page[limit]=10
+  #
+  # Where:
+  #
+  # - <b><tt>page[number]</tt></b> is the current page
+  #
+  # - <b><tt>page[limit]</tt></b> is number of records per page
+  #
+  # The class takes an ActiveDispatch::Request object, an ActiveRecord::Base model
+  # (to generate a pagination sub-query) and two options:
+  #
+  # <b><tt>:max_per_page</tt></b> - maximum number of records per page which defaults to
+  # JsonApiServer::Configuration#default_max_per_page.
+  #
+  # <b><tt>:default_per_page</tt></b> - number of records to show if not specified in <tt>page[limit]</tt>
+  # defaults to JsonApiServer::Configuration#default_per_page).
+  #
+  # ===== Example:
+  #
+  # Create an instance in your controller:
+  #
+  #  pagination = JsonApiServer::Pagination.new(request, Comment, max_per_page: 50, default_per_page: 10)
+  #
+  # Merge pagination sub-query into your ActiveRecord query:
+  #
+  #   recent_comments = Comment.recent.merge(pagination.query)
+  #
+  # Get JsonApiServer::Paginator instance to create links in your JSON serializer:
+  #
+  #   paginator = pagination.paginator_for(recent_comments)
+  #   paginator.as_json # creates JSON API links
+  #
+  # Pass paginator as param to a class inheriting from JsonApiServer::ResourcesSerializer and
+  # it creates the links section for you.
+  #
+  #  class CommentsSerializer < JsonApiServer::ResourcesSerializer
+  #    serializer CommentSerializer
+  #  end
+  #   serializer = CommentsSerializer.new(recent_comments, paginator: paginator)
+  #
+  # ==== Note:
+  # JsonApiServer::Builder class provides an easier way to use this class.
+  #
+  class Pagination
+    # ActionDispatch::Request passed in constructor.
+    attr_reader :request
+
+    # ActiveRecord::Base model passed in constructor.
+    attr_reader :model
+
+    # Query parameters from #request.
+    attr_reader :params
+
+    # Maximum records per page. Prevents users from requesting too many records. Passed
+    # into constructor.
+    attr_reader :max_per_page
+
+    # Default number of records to show per page. If <tt>page[limit]</tt> is not present, it
+    # will use this value. If this is not set, it will use
+    # JsonApiServer.configuration.default_per_page.
+    attr_reader :default_per_page
+
+    # Arguments:
+    # - <tt>request</tt> - ActionDispatch::Request
+    # - <tt>model</tt> - ActiveRecord::Base model. Used to generate sub-query.
+    # - <tt>options</tt> - (Hash)
+    #   - :max_per_page (Integer) - Optional. Defaults to JsonApiServer.configuration.default_max_per_page.
+    #   - :default_per_page (Integer) - Optional. Defaults to JsonApiServer.configuration.default_per_page.
+    #
+    def initialize(request, model, **options)
+      @request = request
+      @model = model
+      @max_per_page = (options[:max_per_page] || self.class.default_max_per_page).to_i
+      @default_per_page = (options[:default_per_page] || self.class.default_per_page).to_i
+      @params = request.query_parameters
+    end
+
+    # Calls WillPaginate 'paginate' method with #page and #per_page. Returns an
+    # ActiveRecord::Relation object (a query fragment) which can be
+    # merged into another query with merge.
+    #
+    # ==== Example:
+    #
+    #  pagination = JsonApiServer::Pagination.new(request, Comment, options)
+    #  recent_comments = Comment.recent.merge(pagination.relation)
+    #
+    def relation
+      @relation ||= model.paginate(page: page, per_page: per_page)
+    end
+
+    alias query relation
+
+    class << self
+      # Default max per page. Defaults to JsonApiServer.configuration.default_max_per_page
+      def default_max_per_page
+        JsonApiServer.configuration.default_max_per_page
+      end
+
+      # Default per page. Defaults to JsonApiServer.configuration.default_per_page.
+      def default_per_page
+        JsonApiServer.configuration.default_per_page
+      end
+    end
+
+    # Create an instance of JsonApiServer::Paginator for a WillPaginate collection. Returns
+    # nil if not a WillPaginate collection.
+    #
+    # params:
+    # - <tt>collection</tt> (WillPaginate collection) - i.e., Comment.recent.paginate(page: x, per_page: y)
+    # - <tt>options</tt> (Hash):
+    #  - <tt>per_page</tt> (Integer) - defaults to self.per_page.
+    #  - <tt>base_url</tt> (String) - defaults to self.base_url (joins JsonApiServer.configuration.base_url with request.path).
+    def paginator_for(collection, options = {})
+      if collection.respond_to?(:current_page) && collection.respond_to?(:total_pages)
+        # call to_i on WillPaginate::PageNumber which DelegateClass(Integer)
+        # paginator(collection.current_page.to_i, collection.total_pages.to_i, options)
+        # HACK: collection.current_page.to_i disappears when merged? works w/o merge.
+        paginator(page, collection.total_pages.to_i, options)
+      end
+    end
+
+    # Number of records per page. From query parameter <tt>page[limit]</tt>.
+    def per_page
+      @per_page ||= begin
+        l = begin
+              params[:page][:limit].to_i
+            rescue
+              default_per_page
+            end
+        l = [max_per_page, l].min
+        l <= 0 ? default_per_page : l
+      end
+    end
+
+    alias limit per_page
+
+    # The current page number. From query parameter page[number]</tt>.
+    def page
+      @page ||= begin
+        n = begin
+              params[:page][:number].to_i
+            rescue
+              1
+            end
+        n <= 0 ? 1 : n
+      end
+    end
+
+    alias number page
+
+    # Joins JsonApiServer::Configuration#base_url with request.path.
+    def base_url
+      @base_url ||= File.join(JsonApiServer.configuration.base_url, request.path)
+    end
+
+    protected
+
+    # Creates an instance of JsonApiServer::Paginator.
+    #
+    # params:
+    # - <tt>current_page</tt> (Integer)
+    # - <tt>total_pages</tt> (Integer)
+    # - <tt>options</tt> (Hash):
+    #  - <tt>per_page</tt> (Integer) - defaults to self.per_page.
+    #  - <tt>base_url</tt> (String) - defaults to self.base_url (joins
+    #                   JsonApiServer::Configuration#base_url with request.path.).
+    def paginator(current_page, total_pages, options = {})
+      per_page = options[:per_page] || self.per_page
+      base_url = options[:base_url] || self.base_url
+      JsonApiServer.paginator(current_page, total_pages, per_page,
+                              base_url, params)
+    end
+  end
+end

data/lib/json_api_server/paginator.rb

@@ -0,0 +1,134 @@
+module JsonApiServer # :nodoc:
+  # Creates JSON API pagination entries per http://jsonapi.org/examples/#pagination.
+  #
+  # JsonApiServer::Paginator#as_json generates a hash like the following which can be
+  # added to JsonApiServer::BaseSerializer#links section.
+  #
+  # - 'next' is nil when self is the last page.
+  # - 'prev' is nil when self is the first page.
+  #
+  # ===== Example:
+  #  "links": {
+  #    "self": "http://example.com/articles?page[number]=3&page[limit]=5",
+  #    "first": "http://example.com/articles?page[number]=1&page[limit]=5",
+  #    "prev": "http://example.com/articles?page[number]=2&page[limit]=5",
+  #    "next": "http://example.com/articles?page[number]=4&page[limit]=5",
+  #    "last": "http://example.com/articles?page[number]=13&page[limit]=5"
+  #  }
+  class Paginator
+    @attrs = %w[first last self next prev]
+
+    # Params:
+    # - <tt>current_page</tt> (Integer)
+    # - <tt>total_pages</tt> (Integer)
+    # - <tt>per_page</tt> (Integer)
+    # - <tt>base_url</tt> (String) - Base url for resource, i.e., <tt>http://example.com/articles</tt>.
+    # - <tt>params</tt> (Hash) - Request parameters. Pagination params are merged into these.
+    def initialize(current_page, total_pages, per_page, base_url, params = {})
+      @current_page = current_page
+      @total_pages = total_pages
+      @per_page = per_page
+      @base_url = base_url
+      @params = params
+    end
+
+    class << self
+      attr_accessor :attrs
+    end
+
+    # First page url.
+    def first
+      @first ||= build_url(merge_params(1))
+    end
+
+    # Last page url.
+    def last
+      @last ||= build_url(merge_params(@total_pages))
+    end
+
+    # Current page url.
+    def self
+      @self ||= build_url(merge_params(@current_page))
+    end
+
+    # Next page url.
+    def next
+      @next ||= begin
+        n = calculate_next
+        n.nil? ? nil : build_url(merge_params(n))
+      end
+    end
+
+    # Previous page url.
+    def prev
+      @prev ||= begin
+        p = calculate_prev
+        p.nil? ? nil : build_url(merge_params(p))
+      end
+    end
+
+    # Returns hash:
+    #  # i.e.,
+    #  {
+    #   self: "http://example.com/articles?page[number]=3&page[limit]=5",
+    #   first: "http://example.com/articles?page[number]=1&page[limit]=5",
+    #   prev: "http://example.com/articles?page[number]=2&page[limit]=5",
+    #   next: "http://example.com/articles?page[number]=4&page[limit]=5",
+    #   last: "http://example.com/articles?page[number]=13&page[limit]=5"
+    #  }
+    def as_json
+      self.class.attrs.each_with_object({}) { |attr, acc| acc[attr] = send(attr); }
+    end
+
+    alias to_h as_json
+
+    # Hash with pagination meta information. Useful for user interfaces, i.e.,
+    # 'page #{current_page} of #{total_pages}'.
+    #
+    #  #i.e.,
+    #  {
+    #    links: {
+    #        current_page: 2,
+    #        total_pages: 13,
+    #        per_page: 5
+    #    }
+    #  }
+    def meta_info
+      {
+        'links' => {
+          'current_page' => @current_page,
+          'total_pages' => @total_pages,
+          'per_page' => @per_page
+        }
+      }
+    end
+
+    protected
+
+    # Merges pagination params with request params. Pagination params look like
+    # this to page[number]=x&page[limit]=y.
+    def merge_params(number)
+      @params.merge(page: { number: number, limit: @per_page })
+    end
+
+    # Merges base_url with modified params. Params are Url encoded, i.e.,
+    # page%5Blimit%5D=5&page%5Bnumber%5D=1
+    def build_url(params)
+      "#{@base_url}?#{params.to_query}"
+    end
+
+    # Calculates next page. Returns nil when value is invalid, i.e.,
+    # exceeds total_pages.
+    def calculate_next
+      n = @current_page + 1
+      n > @total_pages || n <= 0 ? nil : n
+    end
+
+    # Calculates previous page. Returns nil if value is invalid, i.e.,
+    # less than or equal to 0.
+    def calculate_prev
+      p = @current_page - 1
+      p <= 0 || p > @total_pages ? nil : p
+    end
+  end
+end

data/lib/json_api_server/relationships_builder.rb

@@ -0,0 +1,215 @@
+module JsonApiServer # :nodoc:
+  # ==== Description
+  #
+  # Part of http://jsonapi.org/format/#fetching-includes:
+  # "An endpoint may support an include request parameter to allow the client to
+  # customize which related resources should be returned.""
+  #
+  #  ie., GET /articles/1?include=comments,comment.author,tags HTTP/1.1
+  #
+  # Use this class to build <tt>relationships</tt> and <tt>included</tt> sections
+  # in serializers.
+  #
+  # ==== Examples
+  #
+  # Relate, relate conditionally, or relate a collection. In this example,
+  # Publisher is added only if a condition is met (current user is an admin).
+  #
+  #  JsonApiServer::RelationshipsBuilder.new
+  #    .relate('author', AuthorSerializer.new(@object.author))
+  #    .relate_each('comments', @object.comments) {|c| CommentSerializer.new(c)}
+  #    .relationships
+  #
+  #  # produces something like this if current user is an admin:
+  #  # {
+  #  #   "author"=>{
+  #  #      {data: {type: "authors", id: 6, attributes: {first_name: "john", last_name: "Doe"}}}
+  #  #   },
+  #  #   "publisher"=>{
+  #  #     {data: {type: "publishers", id: 1, attributes: {name: "abc"}}}
+  #  #   },
+  #  #   "comments"=>[
+  #  #     {data: {type: "comments", id: 1, attributes: {title: "a", comment: "b"}}},
+  #  #     {data: {type: "comments", id: 2, attributes: {title: "c", comment: "d"}}}
+  #  #   ]
+  #  # }
+  #
+  # <tt>relationships</tt> can include all relationship data or it can reference data in
+  # <tt>included</tt>. To include and relate in one go, #include with the <tt>:relate</tt> option
+  # which takes a BaseSerializer#as_json_options hash.
+  #
+  #  builder = JsonApiServer::RelationshipsBuilder.new
+  #    .include('author', AuthorSerializer.new(@object.author),
+  #        relate: { include: [:relationship_data] })
+  #    .include_each('comments', @object.comments) {|c| CommentSerializer.new(c) }
+  #
+  #  builder.relationships
+  #  # produces something like this if current user is an admin:
+  #  # {
+  #  #  "author" => {
+  #  #    {data: {id: 6, type: "authors"}}
+  #  #   },
+  #  #  "publisher" => {
+  #  #    {links: {self: 'http://.../publishers/1'}}
+  #  #   }
+  #  # }
+  #
+  #  builder.included
+  #  # produces something like this:
+  #  # [
+  #  #   {type: "author", id: 6, attributes: {first_name: "john", last_name: "Doe"}},
+  #  #   {type: "publisher", id: 1, attributes: {name: "abc"}},
+  #  #   {type: "comments", id: 1, attributes: {title: "a", comment: "b"}},
+  #  #   {type: "comments", id: 2, attributes: {title: "c", comment: "d"}}
+  #  # ]
+  #
+  class RelationshipsBuilder
+    def initialize
+      @relationships = {}
+      @included = []
+    end
+
+    # Returns <tt>relationships</tt> object. Relationships added with
+    # #relate, #relate_if, #relate_each and #include (with <tt>:relate</tt> option).
+    def relationships
+      @relationships.each do |k, v|
+        if v.respond_to?(:uniq!)
+          v.uniq!
+          @relationships[k] = v.first if v.length == 1
+        end
+      end
+      @relationships
+    end
+
+    # Returns <tt>included</tt> object. Includes added with
+    # #include, #include_if, #include_each.
+    def included
+      @included.uniq! if @included.respond_to?(:uniq!)
+      @included
+    end
+
+    # Add relationships with this method.
+    #
+    # Arguments:
+    #
+    # - <tt>type</tt> - (String) Relationship type/name.
+    # - <tt>serializer</tt> - (instance of serializer or something that responds to :as_json) Content.
+    #
+    # i.e.,
+    #  JsonApiServer::RelationshipsBuilder.new(['comment.author'])
+    #    .relate('author', author_serializer)
+    #
+    #  # outputs something like...
+    #  # { 'author' => {
+    #  #  :data => {
+    #  #     :type => "people",
+    #  #    :id => 6,
+    #  #     :attributes => {:first_name=>"John", :last_name=>"Steinbeck"}
+    #  #     }
+    #  #   }
+    #  # }
+    #
+    #  JsonApiServer::RelationshipsBuilder.new(['comment.author'])
+    #     .relate('author', author_serializer)
+    #
+    #  # outputs something like...
+    #  # { 'author' => {
+    #  #  :data => {
+    #  #     :type => "people",
+    #  #    :id => 6,
+    #  #     :attributes => {:first_name=>"John", :last_name=>"Steinbeck"}
+    #  #     }
+    #  #   }
+    #  # }
+    def relate(type, serializer)
+      merge_relationship(type, serializer)
+      self
+    end
+
+    # Add a collection to <tt>relationships</tt> with this method.
+    #
+    # Arguments:
+    #
+    # - <tt>type</tt> - (String) Relationship type/name.
+    # - <tt>collection</tt> - Collection of objects to pass to serializer.
+    # - <tt>block</tt> - Block that returns a serializer or something that repsonds_to as_json.
+    #
+    # i.e.,
+    #  JsonApiServer::RelationshipsBuilder.new(['comments'])
+    #    .relate_each('comments', @comments) { |c| CommentSerializer.new(c) }
+    def relate_each(type, collection)
+      collection.each { |item| relate(type, yield(item)) }
+      self
+    end
+
+    # Add to <tt>included</tt> with this method.
+    #
+    # Arguments:
+    #
+    # - <tt>type</tt> - (String) Relationship type/name.
+    # - <tt>serializer</tt> - (instance of serializer or something that responds to :as_json) - relationship content.
+    # - <tt>options</tt> - (Hash) -
+    #   - :relate (Hash) - Optional. Add to relationships. BaseSerializer#as_json_options hash, i.e, <tt>{ include: [:relationship_data] }</tt>.
+    #
+    # i.e.,
+    #  # include and relate
+    #  JsonApiServer::RelationshipsBuilder.new(['comment.author'])
+    #    .include('author', author_serializer,
+    #       relate: {include: [:relationship_data]})
+    #
+    #  # or just include
+    #  JsonApiServer::RelationshipsBuilder.new(['author'])
+    #     .include('author', author_serializer)
+    def include(type, serializer, **options)
+      merge_included(serializer)
+      if options[:relate]
+        serializer.as_json_options = options[:relate]
+        relate(type, serializer)
+      end
+      self
+    end
+
+    # Add a collection to <tt>included</tt> with this method.
+    #
+    # Arguments:
+    #
+    # - <tt>type</tt> - (String) Relationship type/name.
+    # - <tt>collection</tt> - Collection of objects to pass to block.
+    # - <tt>options</tt> - (Hash) -
+    #   - :relate (Hash) - Optional. Add to relationships. BaseSerializer#as_json_options hash, i.e, <tt>{ include: [:relationship_data] }</tt>.
+    # - <tt>block</tt> - Block that returns a serializer or something that repsonds_to as_json.
+    #
+    # i.e.,
+    #
+    #  JsonApiServer::RelationshipsBuilder.new(['comments'])
+    #     .include_each('comments', @comments) {|c| CommentSerializer.new(c)}
+    #
+    def include_each(type, collection, **options)
+      collection.each { |item| include(type, yield(item), options) }
+      self
+    end
+
+    protected
+
+    def merge_relationship(type, value)
+      content = value.as_json if value.respond_to?(:as_json)
+      return if content.blank?
+
+      if @relationships.key?(type)
+        unless @relationships[type].is_a?(Array)
+          @relationships[type] = [@relationships[type]]
+        end
+        @relationships[type].push(content)
+      else
+        @relationships.merge!(type => content)
+      end
+    end
+
+    def merge_included(value)
+      if value.respond_to?(:as_json)
+        content = value.respond_to?(:as_json_options) ? value.as_json(include: [:data]) : value.as_json
+        @included.push(content[:data]) if content.present?
+      end
+    end
+  end
+end