json_api_server 0.0.1

data/lib/json_api_server/resource_serializer.rb

@@ -0,0 +1,245 @@
+module JsonApiServer # :nodoc:
+  # ==== Description
+  #
+  # Serializer class for a resource. Subclasses JsonApiServer::BaseSerializer.
+  #
+  # Example class:
+  #
+  #   class CommentSerializer < JsonApiServer::ResourceSerializer
+  #     resource_type 'comments'
+  #
+  #     def links
+  #       { self: File.join(base_url, "/comments/#{@object.id}") }
+  #     end
+  #
+  #     def data
+  #       {}.tap do |h|
+  #         h['type'] = self.class.type
+  #         h['id'] = @object.id
+  #         h['attributes'] = attributes
+  #         h['relationships'] = inclusions.relationships if inclusions?
+  #       end
+  #     end
+  #
+  #     def included
+  #       inclusions.included if inclusions?
+  #     end
+  #
+  #     protected
+  #
+  #     def attributes
+  #       attributes_builder
+  #         .add_multi(@object, 'title', 'comment')
+  #         .add('created_at', @object.created_at.try(:iso8601, 9))
+  #         .add('updated_at', @object.updated_at.try(:iso8601, 9))
+  #         .attributes
+  #     end
+  #
+  #     def inclusions
+  #       @inclusions ||= begin
+  #         if relationship?('comment.author')
+  #           relationships_builder.relate('author', user_serializer(@object.author))
+  #         end
+  #         if relationship?('comment.author.links')
+  #           relationships_builder.include('author', user_serializer(@object.author),
+  #                                         relate: { include: [:links] })
+  #         end
+  #         relationships_builder
+  #       end
+  #     end
+  #
+  #     def user_serializer(user, as_json_options = { include: [:data] })
+  #       ::UserSerializer.new(
+  #         user,
+  #         includes: includes,
+  #         fields: fields,
+  #         as_json_options: as_json_options
+  #       )
+  #     end
+  #   end
+  #
+  # Create an instance from builder:
+  #
+  #   builder = JsonApiServer::Builder.new(request, Comment.find(params[:id]))
+  #     .add_include(['comment.author', 'comment.author.links'])
+  #     .add_fields
+  #
+  #   serializer = CommentSerializer.from_builder(builder)
+  #
+  class ResourceSerializer < JsonApiServer::BaseSerializer
+    # Array. Relationships to include. Array of strings. From the
+    # 'include' param. Extracted via JsonApiServer::Include#includes which
+    # is also available through JsonApiServer::Builder#includes. Defaults to
+    # nil. Set in initializer options.
+    #
+    # i.e.,
+    #
+    #   GET /articles?include=comments.author,publisher becomes:
+    #   includes = ['comments.author', 'publisher']
+    attr_reader :includes
+
+    # Hash. Fields requested by user. From the 'fields' param. Extracted
+    # via JsonApiServer::Fields#sparse_fields which is also available through
+    # JsonApiServer::Builder#sparse_fields. Defaults to nil. Set in initializer
+    # options.
+    #
+    # i.e.,
+    #
+    #   GET /articles?include=author&fields[articles]=title,body&fields[people]=name becomes:
+    #   fields = {'articles' => ['title', 'body'], 'people' => ['name']}
+    attr_reader :fields
+
+    # * <tt>object</tt> - instance of model or presenter or whatever stores data.
+    # * <tt>options</tt> - Hash (optional):
+    #   * <tt>:includes</tt> - Instance of JsonApiServer::Include or nil. Sets #includes.
+    #   * <tt>:fields</tt> - Instance of JsonApiServer::Fields or nil. Sets #fields.
+    def initialize(object, **options)
+      super(options)
+      @object = object
+      @includes = options[:includes]
+      @fields = options[:fields]
+    end
+
+    class << self
+      # 'type' used in #relationship_data and #data. i.e.:
+      #
+      #   "data": {"type": "articles", "id": 2}
+      def type
+        @type || type_from_class_name
+      end
+
+      # 'type' used in #relationship_data.
+      def resource_type(type)
+        @type = type
+      end
+
+      # * <tt>:builder</tt> - Instance of JsonApiServer::Builder.
+      # #object, #includes and #fields will be extracted from it.
+      # * <tt>options</tt> - Hash, override values from Builder or set additional options.
+      #   * <tt>:includes</tt> - Instance of JsonApiServer::Include or nil. Sets #includes.
+      #   * <tt>:fields</tt> - Instance of JsonApiServer::Fields or nil. Sets #fields.
+      #   * <tt>filter</tt> - Instance of JsonApiServer::Filter or nil. Sets #filter.
+      #   * <tt>:paginator</tt> - Instance of JsonApiServer::Fields or nil. Sets #paginator.
+      #   * <tt>:as_json_options</tt> - See options at JsonApiServer::BaseSerializer#as_json_options.
+      def from_builder(builder, **options)
+        opts = options.merge(fields: options[:fields] || builder.sparse_fields,
+                             includes: options[:includes] || builder.includes,
+                             paginator: options[:paginator] || builder.paginator,
+                             filter: options[:filter] || builder.filter)
+        new(builder.query, opts)
+      end
+
+      protected
+
+      # Get type from class name.
+      def type_from_class_name
+        @type_from_class_name ||= begin
+          class_name = name.split('::').last
+          class_name.downcase!
+          class_name.gsub!(/serializer/, '')
+          class_name.pluralize
+        end
+      end
+    end
+
+    # Content when #as_json_options {include: [:relationship_data]} is specified. Defaults
+    # to { 'type' => <resource_type>, 'id' => <@object.id> }. resource_type can be
+    # set with class method #resource_type, otherwise it will be guessed from
+    # serializer class name.
+    def relationship_data
+      id = @object.try(:id) || @object.try(:[], :id)
+      { 'type' => self.class.type, 'id' => id }
+    end
+
+    protected
+
+    # Returns a new instance of JsonApiServer::AttributesBuilder for
+    # the specified #fields <tt>type</tt>.
+    #
+    # * <tt>type</tt> - the resource type.
+    #
+    # i.e.,
+    #
+    #   # GET /articles?include=author&fields[articles]=title,body&fields[people]=name becomes:
+    #   # fields = {'articles' => ['title', 'body'], 'people' => ['name']}
+    #
+    #   self.attributes_builder_for('articles')
+    #     .add('title', @object.title)
+    #     .add('body', @object.body)
+    #     .add('created_at', @object.created_at)
+    #
+    def attributes_builder_for(type)
+      JsonApiServer::AttributesBuilder.new(fields_for(type))
+    end
+
+    # Instance of JsonApiServer::AttributesBuilder for the class's resource 'type'.
+    #
+    # i.e.,
+    #
+    #   self.attributes_builder  # => attributes_builder_for(self.class.type)
+    #     .add('title', @object.title)
+    #     .add('body', @object.body)
+    #     .add('created_at', @object.created_at)
+    def attributes_builder
+      @attributes_builder ||= attributes_builder_for(self.class.type)
+    end
+
+    # Instance of JsonApiServer::MetaBuilder.
+    #
+    # i.e.,
+    #
+    #  self.meta_builder
+    #     .add('total_records', 35)
+    #  ...
+    #  self.meta_builder
+    #     .add('paging', 'showing 11 - 20')
+    #     .meta # => { 'total_records': 35, 'paging': 'showing 11 - 20' }
+    #
+    def meta_builder
+      @meta_builder ||= JsonApiServer::MetaBuilder.new
+    end
+
+    # Instance of JsonApiServer::RelationshipsBuilder.
+    #
+    # i.e.,
+    #
+    #  self.relationships_builder
+    #     .relate(...)
+    #     .relate_if(...)
+    #     .relate_each(...)
+    #
+    #  self.relationships_builder.relationships # get relationships section
+    #  self.relationships_builder.included # get included section
+    def relationships_builder
+      @relationships_builder ||= JsonApiServer::RelationshipsBuilder.new
+    end
+
+    alias rb relationships_builder
+
+    # Returns true if relationship is in #includes array.
+    #
+    # * <tt>relationship</tt> - Name of relationship. String or symbol.
+    #
+    # i.e.,
+    #
+    #   # GET /articles?include=comment.author,publisher becomes:
+    #   # includes = ['comment.author', 'publisher']
+    #
+    #   self.relationship?('comment.author') # => true
+    #   self.relationship?('addresses') # => false
+    def relationship?(relationship)
+      @includes.respond_to?(:include?) && @includes.include?(relationship.to_s)
+    end
+
+    # Returns true if there are requested inclusions. False otherwise.
+    def inclusions?
+      @includes.respond_to?(:any?) && @includes.any?
+    end
+
+    # Returns the fields for a specific type. i.e., fields_for('articles') or nil
+    # if type doesn't exist or fields is nil.
+    def fields_for(type)
+      @fields.respond_to?(:key) ? @fields[type.to_s] : nil
+    end
+  end
+end

data/lib/json_api_server/resources_serializer.rb

@@ -0,0 +1,131 @@
+# TODO: inheritance is dubious with introduction of :type and relationship_data.
+module JsonApiServer # :nodoc:
+  # ==== Description
+  #
+  # Serializer for a collection/array of resources. Inherits from
+  # JsonApiServer::ResourceSerializer.
+  #
+  # ==== Example
+  #
+  # Given a resource serializer for Topic:
+  #
+  #  class TopicSerializer < JsonApiServer::ResourceSerializer
+  #   resource_type 'topics'
+  #
+  #    def links
+  #      { self: File.join(base_url, "/topics/#{@object.id}") }
+  #    end
+  #
+  #    def data
+  #      {
+  #        type: self.class.type,
+  #        id: @object.id,
+  #        attributes: attributes
+  #      }
+  #    end
+  #
+  #    protected
+  #
+  #    def attributes
+  #      attributes_builder
+  #        .add('book', @object.book)
+  #        .add('author', @object.author)
+  #        .add('quote', @object.quote)
+  #        .add('character', @object.character)
+  #        .add('location', @object.location)
+  #        .add('published', @object.published)
+  #        .add('created_at', @object.created_at.try(:iso8601, 0))
+  #        .add('updated_at', @object.updated_at.try(:iso8601, 0))
+  #        .attributes
+  #    end
+  #  end
+  #
+  # Create a Topics serializer like so:
+  #
+  #  class TopicsSerializer < JsonApiServer::ResourcesSerializer
+  #    serializer TopicSerializer
+  #  end
+  #
+  # Create an instance from builder:
+  #
+  #   builder = JsonApiServer::Builder.new(request, Topic.all)
+  #     .add_pagination(pagination_options)
+  #     .add_filter(filter_options)
+  #     .add_sort(sort_options)
+  #     .add_include(include_options)
+  #     .add_fields
+  #
+  #   # populates links with pagination info, merges data from each
+  #   # Topic serializer instance.
+  #   serializer = TopicsSerializer.from_builder(builder)
+  #
+  class ResourcesSerializer < JsonApiServer::ResourceSerializer
+    # Instance of JsonApiServer::Paginator or nil (default). Based on pagination
+    # params. Extracted via JsonApiServer::Pagination and available
+    # through JsonApiServer::Builder#paginator. Set in initializer options.
+    attr_reader :paginator
+
+    # Instance of JsonApiServer::Filter or nil (default). Based on filter
+    # params. Extracted via JsonApiServer::Filter and available
+    # through JsonApiServer::Builder#filter. Set in initializer options.
+    attr_reader :filter
+
+    class << self
+      attr_reader :objects_serializer
+
+      # A serializer class. If set,'objects' will be converted to instances of
+      # this serializer.
+      def serializer(klass)
+        @objects_serializer = klass
+      end
+    end
+
+    # * <tt>objects</tt> - An array of objects. If #serializer is specified, the
+    #   objects will be converted to this class.
+    # * <tt>options</tt> - Hash:
+    #   * <tt>filter</tt> - Instance of JsonApiServer::Filter or nil. Sets #filter.
+    #   * <tt>:paginator</tt> - Instance of JsonApiServer::Fields or nil. Sets #paginator.
+    #   * <tt>:as_json_options</tt> - See options at JsonApiServer::BaseSerializer#as_json_options.
+    def initialize(objects, **options)
+      super(nil, options)
+      remove_instance_variable(:@object)
+      @paginator = options[:paginator]
+      @filter = options[:filter]
+      @objects = initalize_objects(objects)
+    end
+
+    def links
+      @paginator.try(:as_json) || {}
+    end
+
+    # Subclasses override for customized behaviour.
+    def data
+      data = @objects.try(:map) { |o| o.try(:data) }
+      data.try(:compact!) || data
+    end
+
+    # Subclasses override for customized behaviour.
+    def relationship_data
+      data = @objects.try(:map) { |o| o.try(:relationship_data) }
+      data.try(:compact!) || data
+    end
+
+    # Subclasses override for customized behaviour.
+    def included
+      included = @objects.try(:map) { |o| o.try(:included) }
+      included.try(:flatten!)
+      included.try(:compact!) || included
+    end
+
+    protected
+
+    def initalize_objects(objects)
+      klass = self.class.objects_serializer
+      if klass && objects.respond_to?(:map)
+        objects.map { |object| klass.new(object, includes: includes, fields: fields) }
+      else
+        objects
+      end
+    end
+  end
+end

data/lib/json_api_server/serializer.rb

@@ -0,0 +1,34 @@
+#--
+# TODO: https://github.com/ohler55/oj/issues/199
+#++
+module JsonApiServer # :nodoc:
+  # ==== Description
+  #
+  # to_json serializer method. Used by the various serializers.
+  module Serializer
+    # Serializer options from JsonApiServer::Configuration#serializer_options.
+    def serializer_options
+      JsonApiServer.configuration.serializer_options
+    end
+
+    # Classes override.
+    def as_json
+      {}
+    end
+
+    # Serializes to JSON. Serializer options default to
+    # JsonApiServer.configuration.serializer_options unless
+    # alternate are specified with the <tt>options</tt> parameter.
+    # Default options are:
+    #   escape_mode: :xss_safe,
+    #   time: :xmlschema,
+    #   mode: :compat
+    #
+    # Parameters:
+    # - options (Hash) - OJ serialization options: https://github.com/ohler55/oj#options. If none specified, it uses defaults.
+    def to_json(**options)
+      opts = options.empty? ? serializer_options : options
+      Oj.dump(as_json, opts)
+    end
+  end
+end

data/lib/json_api_server/sort.rb

@@ -0,0 +1,156 @@
+#--
+# TODO:
+#   - Does not return 400 Bad Request if sort attribute is not supported.
+#   - Sort nested relationships specified with dot notation - topic.comments
+#++
+module JsonApiServer # :nodoc:
+  # === Description:
+  # Implements sort parameters per JSON API Spec:
+  # http://jsonapi.org/format/#fetching-sorting.
+  #
+  # From the spec: "The sort order for each sort field MUST be ascending unless it is
+  # prefixed with a minus (U+002D HYPHEN-MINUS, "-", in which case it MUST be
+  # descending."
+  #
+  # This class (1) whitelists sort params, (2) optionally specifies a default order,
+  # and (3) generates a sub-query based on these params.
+  #
+  # === Usage:
+  #
+  # A sort request will look like:
+  #   /topics?sort=-created,title
+  #
+  # This gets converted to an array. Sort order is ASC by default. Minus = DESC.
+  #   ['-created', 'title']
+  #
+  # Sort attributes are configured like so. <tt>:permitted</tt> are whitelisted attributes.
+  # <tt>:default</tt> specifies the default sort order. If a user specifies sort params other
+  # than those in <tt>:permitted</tt>, a JsonApiServer::BadRequest exception is
+  # raised which renders a 400 error.
+  #  {
+  #    permitted: [:id, :title, { created: { col_name: :created_at}],
+  #    default: { id: :desc }
+  #  }
+  # In this example, id, title and created (alias for created_at column)
+  # are permitted sort params.
+  #
+  # ==== Example:
+  #  # create sort options
+  #  sort_options = {
+  #    permitted: [:id, :title, { created: { col_name: :created_at}],
+  #    default: { id: :desc }
+  #  }
+  #
+  #  # create instance
+  #  sort = JsonApiServer::Sort.new(request, Topic, sort_options)
+  #
+  #  # merge into master query
+  #  recent_topics = Topic.recent.merge(sort.query)
+  #
+  #  # see sort params
+  #  puts sort.sort
+  #
+  # ==== Note:
+  # JsonApiServer::Builder class provides an easier way to use this class.
+  #
+  class Sort
+    #--
+    # ActiveRecord::QueryMethods order is defined order(*args)
+    # i.e., User.order(:name, email: :desc)
+    #++
+
+    # Controller request object.
+    attr_reader :request
+
+    # Model passed in constructor.
+    attr_reader :model
+
+    # (Hash) Sort options. Specify the attributes that can be used in ActiveRecord
+    # query method 'sort'. No sort attributes can be used except for those
+    # specified here.
+    #
+    # - <tt>permitted</tt> - array of model attribute names
+    # - <tt>default</tt> - used if no sort params are specified (or rejected)
+    #
+    # i.e.,
+    #
+    # Allows sorting on model attributes :id, :title, :created.
+    # If no sort params are specified in the request, it sorts by 'id' desc.
+    #
+    #  {
+    #    permitted: [:id, :title, { created: { col_name: :created_at}],
+    #    default: { id: :desc }
+    #  }
+    attr_reader :options
+
+    # Request query params (request.query_parameters).
+    attr_reader :params
+
+    # Params:
+    #   - request - instance of request object
+    #   - options - sort options. See #options documentation.
+    def initialize(request, model, options = {})
+      @request = request
+      @model = model
+      @options = options
+      @params = request.query_parameters
+    end
+
+    # Returns an ActiveRecord::Relation if sort_params are present. Otherwise
+    # returns nil. Instance is a query fragment intended to be merged into another
+    # query.
+    #
+    # ==== Example:
+    #
+    #  sort = JsonApiServer::Sort.new(request, Comment, options)
+    #  Comment.recent.merge!(sort.query)
+    #
+    def relation
+      @relation ||= model.order(sort_params) if sort_params.present?
+    end
+
+    alias query relation
+
+    # Sort query parameter params[:sort].
+    def sort
+      @sort ||= params[:sort].to_s
+    end
+
+    # Instance of JsonApiServer::SortConfigs based on #options.
+    def configs
+      @configs ||= JsonApiServer::SortConfigs.new(options)
+    end
+
+    # Calculated ActiveRecord 'order' parameters. Use in queries.
+    def sort_params
+      @sort_params ||= begin
+        attrs = sort.split(',')
+        sort_params = convert(attrs)
+        sort_params.empty? ? configs.default_order : sort_params
+      end
+    end
+
+    protected
+
+    # Converts to ActiveRecord query order parameters; whitelists based on configs.
+    # Raises JsonApiServer::BadRequest with descriptive message if attribute
+    # is not whitelisted.
+    def convert(attrs)
+      whitelisted = []
+
+      attrs.each do |attr|
+        attr.strip!
+        order = attr.start_with?('-') ? :desc : :asc
+        attr_name = order == :desc ? attr.slice(1..attr.length) : attr
+        config = configs.config_for(attr_name)
+        if config.nil?
+          msg = I18n.t('json_api_server.render_400.sort', param: attr_name)
+          raise JsonApiServer::BadRequest, msg
+        end
+        whitelisted << { (config[:col_name] || config[:attr]) => order }
+      end
+
+      whitelisted
+    end
+  end
+end