simple-json-api-serializer 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 70a2dc4601aee95d0b8ca23f13996aa12f55d697
-  data.tar.gz: d9b52897b675d77b5b353195eea2f1bd1c610c33
+  metadata.gz: 26aca00f45d33183b7dd675cb65cc5c0de391c23
+  data.tar.gz: 8a10856e79d6c6190bd9834a50a8f7d3b6b12356
 SHA512:
-  metadata.gz: 01e2a4136d074192f60bb7c54b0f159bec76ae83be357ff97cd2505a6385dec091b6cce68ce23b7a88ab376360d94a70b6fa5b797759e25439edfbb900fd6646
-  data.tar.gz: 983f533a18b6c30f28bf4ddc353e3ffc899d389582f60010610bcf610adcc2f1820470811e5f48dad70d376f878fb93e71d5b691db048487059a9434094c8c20
+  metadata.gz: 8c017a9d09bee70bdeee9bd188734b8e23a082ee32f67d61fb785f4e620a45ce50b5eb84feb59f4a0ba5218748fd5d7a9712f4d0b8cf12cb75b469a1c0507123
+  data.tar.gz: 49970b68ac24fcc874013197ede703328a02e7dc366cce35ac79d721f2d3738bfe30bc7f9846e10322b4ecd0ac98abce899c83bb826ec9e0c6440ce86b425631

data/.gitignore

@@ -0,0 +1 @@
+.*vimrc

data/README.md

@@ -1,7 +1,9 @@
-# Simple JsonApi::Serializer
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/simple/json/api/serializer`. To experiment with that code, run `bin/console` for an interactive prompt.
+# Simple JSONApi::Serializer
 
+* An extremely simple JSON Api serializer.
+* It supports serializing any Ruby object. 
+* It does not target a specific framework.
+* Does not (yet) support links and includes.
 
 ## Installation
 
@@ -21,7 +23,126 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+You can use the JSONApi::Serializer in two ways:
+* In a DSL like manner by declaring your configuration in as subclass of `JSONApi::ObjectSerializerDefinition`
+* By using `JSONApi::Serializer#to_json` directly with an object and a configuration hash
+
+### The DSL way
+
+The simplest serializer you can declare looks like this:
+
+```ruby
+class MyObjectSerializer < JSONApi::ObjectSerializerDefinition
+end
+```
+
+You can then serialize objects with it:
+
+```ruby
+MyObject = Struct.new(:id)
+my_object = MyObject.new(1)
+
+MyObjectSerializer.serialize(my_object)
+```
+
+Which generates:
+
+```json
+{
+  "data": {
+    "type": "my-objects",
+    "id": "1"
+  }
+}
+```
+
+#### Configuring the output
+
+```ruby
+class PersonSerializer < JSONApi::ObjectSerializerDefinition
+  id_attribute :ssn
+  
+  attributes :first_name, :last_name
+end
+
+Person = Struct.new(:ssn, :first_name, :last_name)
+joe = Person.new('X3DAB4CFJ0', 'Joe', 'Strummer')
+
+PersonSerializer.serialize(joe)
+```
+
+Generates:
+
+```json
+{
+  "data": {
+    "type": "persons",
+    "id": "X3DAB4CFJ0",
+    "attributes": {
+      "first-name": "Joe",
+      "last-name":  "Strummer"
+    }
+  }
+}
+```
+
+#### Adding relationships
+
+```ruby
+class PostSerializer < JSONApi::ObjectSerializerDefinition
+  attributes :title, :content
+  
+  has_one  :author
+  has_many :comments
+end
+
+Post = Struct.new(:id, :title, :content, :author, :comments) do
+  def author_id
+    author.id
+  end
+  
+  def comment_ids
+    comments.map(&:id)
+  end
+end
+
+post = Post.new(1, "How to serialize objects", "...", author, comments)
+
+PostSerializer.serialize(post)
+```
+
+Generates:
+
+```json
+{
+  "data": {
+    "type": "posts",
+    "id": "1",
+    "attributes": {
+      "title": "How to serialize objects",
+      "content": "...",
+    },
+    "relationships": {
+      "author": {
+        "data": { "type": "authors", "id": "42" },
+      },
+      "comments": {
+        "data": [
+          { "type": "comments", "id": "1" },
+          { "type": "comments", "id": "2" }
+        ]
+      }
+    }
+  }
+}
+```
+
+If your object does not abide by the `_id` or `_ids` convention for relations,
+you can specify what method should be called to retrieve the foreign key with
+`has_one  :author, foreign_key: :username`
+
+You can also specify the type of the related object with: `has_one :author, type: :user`.
+
 
 ## Development
 

data/lib/json_api/{serializer.rb → object_serializer.rb}

@@ -4,9 +4,15 @@ require 'json_api/relationship_serializer'
 
 
 module JSONApi
-  class Serializer
-    def to_json(object, **options)
-      ActiveSupport::JSON.encode({ data: data_for(object, **options) })
+  class ObjectSerializer
+    def serialize(object, **options)
+      hash = { data: data_for(object, **options) }
+
+      if options[:include].is_a?(Array)
+        hash[:included] = options[:include]
+      end
+
+      ActiveSupport::JSON.encode(hash)
     end
 
     private
@@ -34,10 +40,15 @@ module JSONApi
     end
 
     def resource_identifier_for(object, **options)
-      {
-        type: type_for(object),
-        id:   id_for(object, options)
+      resource_identifier = {
+        type: type_for(object, options)
       }
+
+      unless options[:new_record]
+        resource_identifier[:id] = id_for(object, options)
+      end
+
+      resource_identifier
     end
 
     def relationships_for(object, options)
@@ -61,8 +72,9 @@ module JSONApi
       canonicalize_id(object.send(id_attribute))
     end
 
-    def type_for(object)
-      canonicalize_type_name(object.class.name)
+    def type_for(object, **options)
+      type_name = options[:type] || object.class.name
+      canonicalize_type_name(type_name)
     end
 
     def canonicalize_id(id)

data/lib/json_api/object_serializer_definition.rb

@@ -1,14 +1,14 @@
-require 'json_api/serializer'
+require 'json_api/object_serializer'
 
 module JSONApi
   class ObjectSerializerDefinition
     class << self
-      def serialize(object)
-        Serializer.new.to_json(object, {
-          id_attribute:  id_attribute,
-          attributes:    attributes,
-          relationships: relationships
-        })
+      def serialize(object, **options)
+        options[:id_attribute]  ||= id_attribute
+        options[:attributes]    ||= attributes
+        options[:relationships] ||= relationships
+
+        ObjectSerializer.new.serialize(object, **options)
       end
 
       def inherited(specialization)

data/lib/json_api/relationship_serializer.rb

@@ -19,14 +19,24 @@ module JSONApi
 
     protected
 
-    def type_for(options)
-      options[:type] || options[:name]
+    def type_for(object, options)
+      if options[:polymorphic]
+        foreign_type_key =
+          options[:foreign_type_key] ||  "#{key_base_for(options)}_type"
+        object.send(foreign_type_key)
+      else
+        options[:type] || options[:name]
+      end
     end
 
-    def key_for(options)
+    def key_base_for(options)
       options[:name].to_s.singularize
     end
 
+    def key_for(options)
+      key_base_for(options)
+    end
+
     def relationship_for(object, **options)
       object.send(options[:key] || key_for(options))
     end
@@ -47,7 +57,7 @@ module JSONApi
 
       def data_for(object, options)
         ids = relationship_for(object, options)
-        ids.map { |id| resource_identifier_for(type_for(options), id) }
+        ids.map { |id| resource_identifier_for(type_for(object, options), id) }
            .compact
       end
     end
@@ -59,7 +69,7 @@ module JSONApi
 
       def data_for(object, options)
         id = relationship_for(object, options)
-        resource_identifier_for(type_for(options), id)
+        resource_identifier_for(type_for(object, options), id)
       end
     end
   end

data/lib/json_api/version.rb

@@ -0,0 +1,3 @@
+module JSONApi
+  VERSION = '0.2.0'
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple-json-api-serializer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Marten Schilstra
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-09-18 00:00:00.000000000 Z
+date: 2015-09-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -75,6 +75,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".gitignore"
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
@@ -83,10 +84,11 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- lib/json_api/object_serializer.rb
 - lib/json_api/object_serializer_definition.rb
 - lib/json_api/relationship_serializer.rb
-- lib/json_api/serializer.rb
 - lib/json_api/utils.rb
+- lib/json_api/version.rb
 - lib/simple/json/api/serializer.rb
 - lib/simple/json/api/serializer/version.rb
 - simple-json-api-serializer.gemspec
@@ -110,7 +112,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5.1
+rubygems_version: 2.4.6
 signing_key: 
 specification_version: 4
 summary: An extremely simple JSON Api serializer