jsonapi-materializer 1.0.0.rc2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 839a143859ef0a7e0a4cdbb14df6f244379dcaffcdee698e1f5b84db81f1e17d
+  data.tar.gz: 8053caead68127f9819da92c4e7adf02ab84ba0bd39b5da9ebefb47c2b3cfc1e
+SHA512:
+  metadata.gz: 329f5f40bc229719d95bfa85cf4969d0cbac81eed8315703602d7518db2b5d114db13b4253945248ba99689f37b5a968c918b0c6065e3a90e7f262c997584dde
+  data.tar.gz: 1d08b4783f94b7b55cb38e5fb664ed1dc36f2ddc41f67f119f6338aac3d6d6d2d6de6caa0093ba7488169b834ad0119d60527b60ee6c62a810c9f72b4bc5b56a

data/README.md

@@ -0,0 +1,211 @@
+# jsonapi-materializer
+
+  - [![Build](http://img.shields.io/travis-ci/krainboltgreene/jsonapi-materializer.rb.svg?style=flat-square)](https://travis-ci.org/krainboltgreene/jsonapi-materializer.rb)
+  - [![Downloads](http://img.shields.io/gem/dtv/jsonapi-materializer.svg?style=flat-square)](https://rubygems.org/gems/jsonapi-materializer)
+  - [![Version](http://img.shields.io/gem/v/jsonapi-materializer.svg?style=flat-square)](https://rubygems.org/gems/jsonapi-materializer)
+
+jsonapi-materializer is a way to turn data objects (for example, active record models) into json:api responses. Largely the library doesn't care *what* it's given, as long as it responds to certain calls.
+
+
+## Using
+
+Lets say we have a simple rails application setup for our project. We'll define the model first:
+
+``` ruby
+class Account < ApplicationRecord
+  has_many(:articles)
+  has_many(:comments)
+
+  def self.schema
+    ActiveRecord::Migration.create_table(:accounts, :force => true) do |table|
+      table.text(:name, :null => false)
+      table.timestamps(:null => false)
+    end
+  end
+end
+```
+
+And a controller:
+
+``` ruby
+class AccountsController < ApplicationController
+  def index
+    render(
+      :json => AccountMaterializer::Collection.new(:object => object)
+    )
+  end
+
+  def show
+    render(
+      :json => AccountMaterializer::Resource.new(:object => object)
+    )
+  end
+end
+```
+
+Finally, lets setup `JSONAPI::Materializer`:
+
+``` ruby
+JSONAPI::Materializer.configuration do |let|
+  let.default_origin = "http://localhost:3001"
+end
+```
+
+Now you need to define a materializer, which is a class that determines how and what to return as a json:api response:
+
+``` ruby
+class AccountMaterializer
+  include(JSONAPI::Materializer::Resource)
+
+  type(:accounts)
+
+  has_many(:reviews, :class_name => "ReviewMaterializer")
+
+  has(:name)
+end
+```
+
+That's it! Your endpoint should correctly return:
+
+``` json
+{
+  "links": {
+    "self": "http://localhost:3001/accounts/cf305673-ce1f-4605-8aa4-cba33a6a5a17"
+  },
+  "data": {
+    "id": "cf305673-ce1f-4605-8aa4-cba33a6a5a17",
+    "type": "accounts",
+    "attributes": {
+      "name": "Sally Stuthers"
+    },
+    "relationships": {
+      "reviews": {
+        "data": [
+          {
+            "id": "91a8ca48-df58-423c-bf36-344cd07e1a51",
+            "type": "reviews"
+          }
+        ],
+        "links": {
+          "self": "http://localhost:3001/accounts/cf305673-ce1f-4605-8aa4-cba33a6a5a17/relationships/reviews",
+          "related": "http://localhost:3001/accounts/cf305673-ce1f-4605-8aa4-cba33a6a5a17/reviews"
+        }
+      }
+    },
+    "links": {
+      "self": "http://localhost:3001/accounts/cf305673-ce1f-4605-8aa4-cba33a6a5a17"
+    }
+  }
+}
+```
+
+You're going to want to handle both sparse fieldset and includes, but materializer doesn't do any of that work for you:
+
+``` ruby
+class AccountsController < ApplicationController
+  def index
+    render(
+      :json => AccountMaterializer::Collection.new(
+        :object => object,
+        :selects => {"accounts" => ["name"]},
+        :includes => [["reviews"]]
+      )
+    )
+  end
+end
+```
+
+We suggest [jsonapi-realizer](https://github.com/krainboltgreene/jsonapi-realizer.rb) to handle this for you.
+
+
+### rails
+
+There is *nothing* specific about rails for this library, it can be used in any framework. You just need:
+
+  0. A place to turn models into json (rails controller)
+  0. A place to store the configuration at boot (rails initializers)
+
+
+### policies (aka pundit)
+
+If you're using some sort of policy logic like pundit you'll have the ability to pass it as a context to the materializer:
+
+``` ruby
+class AccountsController < ApplicationController
+  def show
+    context = {
+      :policy => policy
+    }
+    render(
+      :json => AccountMaterializer::Resource.new(:object => object, :context => context)
+    )
+  end
+end
+```
+
+And now the use of that context object:
+
+``` ruby
+class AccountMaterializer
+  include(JSONAPI::Materializer::Resource)
+
+  type(:accounts)
+
+  has_many(:reviews, :class_name => "ReviewMaterializer")
+
+  has(:name, :visible => :readable_attribute?)
+
+  private def readable_attribute?(attribute)
+    context.policy.read_attribute?(attribute.from)
+  end
+end
+```
+
+You'll notice that context is an object, not a hash, when referenced on the materializer. That's because we give you the ability to enforce the context for saftey:
+
+``` ruby
+
+class AccountMaterializer
+  include(JSONAPI::Materializer::Resource)
+
+  type(:accounts)
+
+  has_many(:reviews, :class_name => "ReviewMaterializer")
+
+  has(:name, :visible => :readable_attribute?)
+
+  context.validates_presence_of(:policy)
+
+  private def readable_attribute?(attribute)
+     context.policy.read_attribute?(attribute.from)
+  end
+end
+```
+
+These are just aliases for ActiveModel::Validations.
+
+
+### Sister Projects
+
+I'm already using jsonapi-materializer. and it's sister project [jsonapi-realizer](https://github.com/krainboltgreene/jsonapi-realizer.rb) in a new gem of mine that allows services to be discoverable: [jsonapi-home](https://github.com/krainboltgreene/jsonapi-home.rb).
+
+
+## Installing
+
+Add this line to your application's Gemfile:
+
+    $ bundle add jsonapi-materializer
+
+Or install it yourself with:
+
+    $ gem install jsonapi-materializer
+
+
+## Contributing
+
+  1. Read the [Code of Conduct](/CONDUCT.md)
+  2. Fork it
+  3. Create your feature branch (`git checkout -b my-new-feature`)
+  4. Commit your changes (`git commit -am 'Add some feature'`)
+  5. Push to the branch (`git push origin my-new-feature`)
+  6. Create new Pull Request

data/Rakefile

@@ -0,0 +1,12 @@
+#!/usr/bin/env rake
+
+require("bundler/gem_tasks")
+require("rspec/core/rake_task")
+
+desc("Run all the tests in spec")
+RSpec::Core::RakeTask.new(:spec) do |let|
+  let.pattern = "lib/**{,/*/**}/*_spec.rb"
+end
+
+desc("Default: run tests")
+task(:default => :spec)

data/lib/jsonapi-materializer.rb

@@ -0,0 +1,3 @@
+module JSONAPI
+  require_relative("jsonapi/materializer")
+end

data/lib/jsonapi/materializer.rb

@@ -0,0 +1,36 @@
+require("ostruct")
+require("addressable")
+require("active_model")
+require("kaminari")
+require("active_support/concern")
+require("active_support/core_ext/enumerable")
+require("active_support/core_ext/string")
+require("active_support/core_ext/module")
+
+module JSONAPI
+  MEDIA_TYPE = "application/vnd.api+json".freeze unless const_defined?("MEDIA_TYPE")
+
+  module Materializer
+    require_relative("materializer/version")
+    require_relative("materializer/error")
+    require_relative("materializer/configuration")
+    require_relative("materializer/controller")
+
+    @configuration ||= Configuration.new(
+      :default_invalid_accept_exception => JSONAPI::Materializer::Error::InvalidAcceptHeader,
+      :default_missing_accept_exception => JSONAPI::Materializer::Error::MissingAcceptHeader,
+      :default_identifier => :id
+    )
+    require_relative("materializer/collection")
+    require_relative("materializer/context")
+    require_relative("materializer/resource")
+
+    def self.configuration
+      if block_given?
+        yield(@configuration)
+      else
+        @configuration
+      end
+    end
+  end
+end

data/lib/jsonapi/materializer/collection.rb

@@ -0,0 +1,87 @@
+module JSONAPI
+  module Materializer
+    module Collection
+      SELF_TEMPLATE = "{origin}/{type}".freeze
+
+      extend(ActiveSupport::Concern)
+      include(ActiveModel::Model)
+
+      attr_accessor(:object)
+      attr_writer(:selects)
+      attr_writer(:includes)
+      attr_writer(:pagination)
+      attr_accessor(:context)
+
+      delegate(:first_page?, :to => :object)
+      delegate(:prev_page, :to => :object)
+      delegate(:total_pages, :to => :object)
+      delegate(:next_page, :to => :object)
+      delegate(:last_page?, :to => :object)
+      delegate(:limit_value, :to => :object)
+
+      def as_json(*)
+        {
+          :links => {
+            :first => unless total_pages.zero? || first_page? then links_pagination.expand(:offset => 1, :limit => limit_value).to_s end,
+            :prev => unless total_pages.zero? || first_page? then links_pagination.expand(:offset => prev_page, :limit => limit_value).to_s end,
+            :self => unless total_pages.zero? then links_self end,
+            :next => unless total_pages.zero? || last_page? then links_pagination.expand(:offset => next_page, :limit => limit_value).to_s end,
+            :last => unless total_pages.zero? || last_page? then links_pagination.expand(:offset => total_pages, :limit => limit_value).to_s end
+          }.compact,
+          :data => resources,
+          :included => included
+        }.transform_values(&:presence).compact
+      end
+
+      private def materializers
+        @materializers ||= object.map {|subobject| self.class.parent.new(:object => subobject, :selects => selects, :includes => includes, :context => context)}
+      end
+
+      private def links_pagination
+        Addressable::Template.new(
+          "#{origin}/#{type}?page[offset]={offset}&page[limit]={limit}"
+        )
+      end
+
+      private def links_self
+        Addressable::Template.new(
+          "#{origin}/#{type}"
+        ).pattern
+      end
+
+      private def origin
+        self.class.parent.instance_variable_get(:@origin)
+      end
+
+      private def type
+        self.class.parent.instance_variable_get(:@type)
+      end
+
+      private def resources
+        @resources ||= materializers.map(&:as_data)
+      end
+
+      private def selects
+        @selects
+      end
+
+      private def includes
+        @includes || []
+      end
+
+      private def included
+        @included ||= materializers.flat_map do |materializer|
+          includes.flat_map do |path|
+            path.reduce(materializer) do |subject, key|
+              if subject.is_a?(Array)
+                subject.map {|related_subject| related_subject.relation(key).for(related_subject)}
+              else
+                subject.relation(key).for(subject)
+              end
+            end
+          end
+        end.uniq.map(&:as_data)
+      end
+    end
+  end
+end

data/lib/jsonapi/materializer/collection_spec.rb

@@ -0,0 +1,103 @@
+require("spec_helper")
+
+RSpec.describe(JSONAPI::Materializer::Collection) do
+  let(:described_class) {ArticleMaterializer::Collection}
+  let(:policy) {Class.new { def read_attribute?(name); true end}}
+  let(:collection) {described_class.new(:object => object, :includes => [["comments"], ["author"]], :context => {:policy => policy.new})}
+
+  describe("#as_json") do
+    subject {collection.as_json.deep_stringify_keys}
+
+    before do
+      Account.create!(:id => 9, :name => "Dan Gebhardt", :twitter => "dgeb")
+      Account.create!(:id => 2, :name => "DHH", :twitter => "DHH")
+      Article.create!(:id => 1, :title => "JSON API paints my bikeshed!", :account => Account.find(9))
+      Article.create!(:id => 2, :title => "Rails is Omakase", :account => Account.find(9))
+      Article.create!(:id => 3, :title => "What is JSON:API?", :account => Account.find(9))
+      Comment.create!(:id => 5, :body => "First!", :article => Article.find(1), :account => Account.find(2))
+      Comment.create!(:id => 12, :body => "I like XML better", :article => Article.find(1), :account => Account.find(9))
+    end
+
+    context("when the list has items") do
+      let(:object) {Kaminari.paginate_array(Article.all).page(1).per(1)}
+
+      it("has a data key at root with the resources") do
+        expect(subject.fetch("data")).to(eq([{
+          "id" => "1",
+          "type" => "articles",
+          "attributes" => {
+            "title" => "JSON API paints my bikeshed!"
+          },
+          "relationships" => {
+            "author" => {
+              "data" => {"id" => "9", "type" => "people"},
+              "links" => {
+                "self" => "http://example.com/articles/1/relationships/author",
+                "related" => "http://example.com/articles/1/author"
+              }
+            },
+            "comments" => {
+              "data" => [
+                {"id" => "5", "type" => "comments"},
+                {"id" => "12", "type" => "comments"}
+              ],
+              "links" => {
+                "self" => "http://example.com/articles/1/relationships/comments",
+                "related" => "http://example.com/articles/1/comments"
+              }
+            }
+          },
+          "links" => {
+            "self" => "http://example.com/articles/1"
+          }
+        }]))
+      end
+
+      it("has a links key at root with pagination") do
+        expect(subject.fetch("links")).to(eq(
+          "self" => "http://example.com/articles",
+          "next" => "http://example.com/articles?page[offset]=2&page[limit]=1",
+          "last" => "http://example.com/articles?page[offset]=3&page[limit]=1"
+        ))
+      end
+
+      it("has a included key at root with included models") do
+        expect(subject.fetch("included")).to(include(
+          {
+            "id" => "5",
+            "type" => "comments",
+            "attributes"=>{"body"=>"First!"},
+            "relationships" => {
+              "author" => {"data" => {"id" => "2", "type" => "people"}, "links" => {"self" => "http://example.com/comments/5/relationships/author", "related" => "http://example.com/comments/5/author"}},
+              "article" => {"data" => {"id" => "1", "type" => "articles"}, "links" => {"self" => "http://example.com/comments/5/relationships/article", "related" => "http://example.com/comments/5/article"}}
+            },
+            "links" => {"self" => "http://example.com/comments/5"}
+          },
+          {
+            "id" => "12",
+            "type" => "comments",
+            "attributes"=>{"body"=>"I like XML better"},
+            "relationships" => {
+              "author" => {"data" => {"id" => "9", "type" => "people"}, "links" => {"self" => "http://example.com/comments/12/relationships/author", "related" => "http://example.com/comments/12/author"}},
+              "article" => {"data" => {"id" => "1", "type" => "articles"}, "links" => {"self" => "http://example.com/comments/12/relationships/article", "related" => "http://example.com/comments/12/article"}}
+            },
+            "links" => {"self" => "http://example.com/comments/12"}
+          },
+          {
+            "id" => "9",
+            "type" => "people",
+            "attributes"=>{"name"=>"Dan Gebhardt"},
+            "relationships" => {
+              "comments" => {"data" => [{"id" => "12", "type" => "comments"}], "links" => {"self" => "http://example.com/people/9/relationships/comments", "related" => "http://example.com/people/9/comments"}},
+              "articles" => {
+                "data" => [{"id" => "1", "type" => "articles"}, {"id" => "2", "type" => "articles"}, {"id" => "3", "type" => "articles"}],
+                "links" => {"self" => "http://example.com/people/9/relationships/articles", "related" => "http://example.com/people/9/articles"}
+              }
+            },
+            "links" => {"self" => "http://example.com/people/9"}
+          }
+        ))
+      end
+    end
+  end
+end