jsonapi-serializers 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 035748d359ee3c492b7867f9dd5548960df3cb78
+  data.tar.gz: 2d6e4b038d482c9de6b9d3972778082c74b36ba9
+SHA512:
+  metadata.gz: 79ac938adcc1fdcc64a43c7237c4b6d1fed837f4d8325312f9a901bd0faf3b06296425e4c2c83b3da518b7813d148f2532c234687f39ceba5e8ab824836993ab
+  data.tar.gz: 167c5d8970366dce05af73431498cc5d5a3d0a0dc585437bc5a4e4e3f126106fec046e03578593031d5976f0cd4bfda7204d9658dc01688b992251c511253f21

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.DS_Store

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format d
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.1.1
+  - 2.2.2
+  - ruby-head
+script: bundle exec rspec

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in jsonapi-serializers.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Mike Fotinakis
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,417 @@
+# JSONAPI::Serializers
+
+JSONAPI::Serializers is a simple library for serializing Ruby objects and their relationships into the [JSON:API format](http://jsonapi.org/format/).
+
+As of writing, the JSON:API spec is approaching v1 and still undergoing changes. This library supports RC3+ and aims to keep up with the continuing development changes.
+
+* [Features](#features)
+* [Installation](#installation)
+* [Usage](#usage)
+  * [Define a serializer](#define-a-serializer)
+  * [Serialize an object](#serialize-an-object)
+  * [Serialize a collection](#serialize-a-collection)
+  * [Null handling](#null-handling)
+  * [Custom attributes](#custom-attributes)
+  * [More customizations](#more-customizations)
+* [Relationships](#relationships)
+  * [Compound documents and includes](#compound-documents-and-includes)
+  * [Relationship path handling](#relationship-path-handling)
+* [Rails example](#rails-example)
+* [Unfinished business](#unfinished-business)
+* [Contributing](#contributing)
+
+## Features
+
+* Works with **any Ruby web framework**, including Rails, Sinatra, etc. This is a pure Ruby library.
+* Supports the readonly features of the JSON:API spec.
+  * **Full support for compound documents** ("side-loading") and the `include` parameter.
+* Similar interface to ActiveModel::Serializers, should provide an easy migration path.
+* Intentionally unopinionated and simple, allows you to structure your app however you would like and then serialize the objects at the end.
+
+JSONAPI::Serializers was built as an intentionally simple serialization interface. It makes no assumptions about your database structure or routes and it does not provide controllers or any create/update interface to the objects. It is a library, not a framework. You will probably still need to do work to make your API fully compliant with the nuances of the [JSON:API spec](http://jsonapi.org/format/), for things like supporting `/links` routes and for supporting write actions like creating or updating objects. If you are looking for a more complete and opinionated framework, see the [jsonapi-resources](https://github.com/cerebris/jsonapi-resources) project.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'jsonapi-serializers'
+```
+
+Or install directly with `gem install jsonapi-serializers`.
+
+## Usage
+
+### Define a serializer
+
+```ruby
+require 'jsonapi-serializers'
+
+class PostSerializer
+  include JSONAPI::Serializer
+  
+  attribute :title
+  attribute :content
+end
+```
+
+### Serialize an object
+
+```ruby
+JSONAPI::Serializer.serialize(post)
+```
+
+Returns a hash:
+```json
+{
+  "data": {
+    "id": "1",
+    "type": "posts",
+    "attributes": {
+      "title": "Hello World",
+      "content": "Your first post"
+    },
+    "links": {
+      "self": "/posts/1"
+    }
+  }
+}
+```
+
+### Serialize a collection
+
+```ruby
+JSONAPI::Serializer.serialize(posts, is_collection: true)
+```
+
+Returns:
+
+```json
+{
+  "data": [
+    {
+      "id": "1",
+      "type": "posts",
+      "attributes": {
+        "title": "Hello World",
+        "content": "Your first post"
+      },
+      "links": {
+        "self": "/posts/1"
+      }
+    },
+    {
+      "id": "2",
+      "type": "posts",
+      "attributes": {
+        "title": "Hello World again",
+        "content": "Your second post"
+      },
+      "links": {
+        "self": "/posts/2"
+      }
+    }
+  ]
+}
+```
+
+You must always pass `is_collection: true` when serializing a collection, see [Null handling](#null-handling).
+
+### Null handling
+
+```ruby
+JSONAPI::Serializer.serialize(nil)
+```
+
+Returns:
+```json
+{
+  "data": null
+}
+```
+
+And serializing an empty collection:
+```ruby
+JSONAPI::Serializer.serialize([], is_collection: true)
+```
+
+Returns:
+```json
+{
+  "data": []
+}
+```
+
+Note that the JSON:API spec distinguishes in how null/empty is handled for single objects vs. collections, so you must always provide `is_collection: true` when serializing multiple objects. If you attempt to serialize multiple objects without this flag (or a single object with it on) a `JSONAPI::Serializer::AmbiguousCollectionError` will be raised.
+
+### Custom attributes
+
+By default the serializer looks for the same name of the attribute on the object it is given. You can customize this behavior by providing a block to the attribute:
+
+```ruby
+  attribute :content do
+    object.body
+  end
+```
+
+The block is evaluated within the serializer instance, so it has access to the `object` and `context` instance variables.
+
+### More customizations
+
+Many other formatting and customizations are possible by overriding any of the following instance methods on your serializers.
+
+```ruby
+  # Override this to customize the JSON:API "id" for this object.
+  # Always return a string from this method to conform with the JSON:API spec.
+  def id
+    object.id.to_s
+  end
+```
+```ruby
+  # Override this to customize the JSON:API "type" for this object.
+  # By default, the type is the object's class name lowercased, pluralized, and dasherized,
+  # per the spec naming recommendations: http://jsonapi.org/recommendations/#naming
+  # For example, 'MyApp::LongCommment' will become the 'long-comments' type.
+  def type
+    object.class.name.demodulize.tableize.dasherize
+  end
+```
+```ruby
+  # Override this to customize how attribute names are formatted.
+  # By default, attribute names are dasherized per the spec naming recommendations:
+  # http://jsonapi.org/recommendations/#naming
+  def format_name(attribute_name)
+    attribute_name.to_s.dasherize
+  end
+```
+```ruby
+  # The opposite of format_name. Override this if you override format_name.
+  def unformat_name(attribute_name)
+    attribute_name.to_s.underscore
+  end
+```
+```ruby
+  # Override this to provide resource-object metadata.
+  # http://jsonapi.org/format/#document-structure-resource-objects
+  def meta
+  end
+```
+```ruby
+  def self_link
+    "/#{type}/#{id}"
+  end
+```
+```ruby
+  def relationship_self_link(attribute_name)
+    "#{self_link}/links/#{format_name(attribute_name)}"
+  end
+```
+```ruby
+  def relationship_related_link(attribute_name)
+    "#{self_link}/#{format_name(attribute_name)}"
+  end
+```
+
+## Relationships
+
+You can easily specify relationships with the `has_one` and `has_many` directives.
+
+```ruby
+class BaseSerializer
+  include JSONAPI::Serializer
+end
+
+class PostSerializer < BaseSerializer
+  attribute :title
+  attribute :content
+
+  has_one :author
+  has_many :comments
+end
+
+class UserSerializer < BaseSerializer
+  attribute :name
+end
+
+class CommentSerializer < BaseSerializer
+  attribute :content
+
+  has_one :user
+end
+```
+
+Note that when serializing a post, the `author` association will come from the `author` attribute on the `Post` instance, no matter what type it is (in this case it is a `User`). This will work just fine, because JSONAPI::Serializers automatically finds serializer classes by appending `Serializer` to the object's class name. This behavior can be customized.
+
+Because the full class name is used when discovering serializers, JSONAPI::Serializers works with any custom namespaces you might have, like a Rails Engine or standard Ruby module namespace.
+
+### Compound documents and includes
+
+> To reduce the number of HTTP requests, servers MAY allow responses that include related resources along with the requested primary resources. Such responses are called "compound documents".
+> [JSON:API Compound Documents](http://jsonapi.org/format/#document-structure-compound-documents)
+
+JSONAPI::Serializers supports compound documents with a simple `include` parameter.
+
+For example:
+
+```ruby
+JSONAPI::Serializer.serialize(post, include: ['author', 'comments', 'comments.user'])
+```
+
+Returns:
+
+```json
+
+  "data": {
+    "id": "1",
+    "type": "posts",
+    "attributes": {
+      "title": "Hello World",
+      "content": "Your first post"
+    },
+    "links": {
+      "self": "/posts/1",
+      "author": {
+        "self": "/posts/1/links/author",
+        "related": "/posts/1/author",
+        "linkage": {
+          "type": "users",
+          "id": "1"
+        }
+      },
+      "comments": {
+        "self": "/posts/1/links/comments",
+        "related": "/posts/1/comments",
+        "linkage": [
+          {
+            "type": "comments",
+            "id": "1"
+          }
+        ]
+      }
+    }
+  },
+  "included": [
+    {
+      "id": "1",
+      "type": "users",
+      "attributes": {
+        "name": "Post Author"
+      },
+      "links": {
+        "self": "/users/1"
+      }
+    },
+    {
+      "id": "1",
+      "type": "comments",
+      "attributes": {
+        "content": "Have no fear, sers, your king is safe."
+      },
+      "links": {
+        "self": "/comments/1",
+        "user": {
+          "self": "/comments/1/links/user",
+          "related": "/comments/1/user",
+          "linkage": {
+            "type": "users",
+            "id": "2"
+          }
+        }
+      }
+    },
+    {
+      "id": "2",
+      "type": "users",
+      "attributes": {
+        "name": "Barristan Selmy"
+      },
+      "links": {
+        "self": "/users/2"
+      }
+    }
+  ]
+}
+```
+
+Notice a few things:
+* The [primary data](http://jsonapi.org/format/#document-structure-top-level) now includes "linkage" information for each relationship that was included.
+* The related objects themselves are loaded in the top-level `included` member.
+* The related objects _also_ include "linkage" information when a deeper relationship is also present in the compound document. This is a very powerful feature of the JSON:API spec, and allows you to deeply link complicated relationships all in the same document and in a single HTTP response. JSONAPI::Serializers automatically includes the correct linkage information for whatever `include` paths you specify. This conforms to this part of the spec:
+    
+  > Note: Resource linkage in a compound document allows a client to link together all of the included resource objects without having to GET any relationship URLs.
+  > [JSON:API Resource Relationships](http://jsonapi.org/format/#document-structure-resource-relationships)
+
+#### Relationship path handling
+ 
+The `include` param also accepts a string of [relationship paths](http://jsonapi.org/format/#fetching-includes), ie. `include: 'author,comments,comments.user'` so you can pass an `?include` query param directly through to the serialize method. Be aware that letting users pass arbitrary relationship paths might introduce security issues depending on your authorization setup, where a user could `include` a relationship they might not be authorized to see directly. Be aware of what you allow API users to include.
+
+## Rails example
+
+```ruby
+# app/serializers/base_serializer.rb
+class BaseSerializer
+  include JSONAPI::Serializer
+
+  def self_link
+    "/api/v1#{super}"
+  end
+end
+
+# app/serializers/post_serializer.rb
+class PostSerializer < BaseSerializer
+  attribute :title
+  attribute :content
+end
+
+# app/controllers/api/v1/base_controller.rb
+class Api::V1::BaseController < ActionController::Base
+  # Convenience methods for serializing models:
+  def serialize_model(model, options = {})
+    options[:is_collection] = false
+    JSONAPI::Serializer.serialize(model, options)
+  end
+
+  def serialize_models(models, options = {})
+    options[:is_collection] = true
+    JSONAPI::Serializer.serialize(models, options)
+  end
+end
+
+# app/controllers/api/v1/posts_controller.rb
+class Api::V1::ReposController < Api::V1::BaseController
+  def index
+    posts = Post.all
+    render json: serialize_models(posts)
+  end
+
+  def show
+    post = Post.find(params[:id])
+    render json: serialize_model(post)
+  end
+end
+
+# lib/jsonapi_mimetypes.rb
+# Without this mimetype registration, controllers will not automatically parse JSON API params.
+module JSONAPI
+  MIMETYPE = "application/vnd.api+json"
+end
+Mime::Type.register(JSONAPI::MIMETYPE, :api_json)
+ActionDispatch::ParamsParser::DEFAULT_PARSERS[Mime::Type.lookup(JSONAPI::MIMETYPE)] = lambda do |body|
+  JSON.parse(body)
+end
+```
+
+## Unfinished business
+
+* Support for passing `context` through to serializers is partially complete, but needs more work.
+* Support for a `serializer_class` attribute on objects that overrides serializer discovery, would love a PR contribution for this.
+* Support for the `fields` spec is planned, would love a PR contribution for this.
+* Support for pagination/sorting is unlikely to be supported because it would likely involve coupling to ActiveRecord, but please open an issue if you have ideas of how to support this generically.
+
+## Contributing
+
+1. Fork it ( https://github.com/fotinakis/jsonapi-serializers/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/jsonapi-serializers.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'jsonapi-serializers/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "jsonapi-serializers"
+  spec.version       = JSONAPI::Serializer::VERSION
+  spec.authors       = ["Mike Fotinakis"]
+  spec.email         = ["mike@fotinakis.com"]
+  spec.summary       = %q{Pure Ruby serializers conforming to the JSON:API spec.}
+  spec.description   = %q{}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activesupport"
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.2"
+  spec.add_development_dependency "factory_girl", "~> 4.5"
+end

data/lib/jsonapi-serializers/attributes.rb

@@ -0,0 +1,58 @@
+module JSONAPI
+  module Attributes
+    def self.included(target)
+      target.send(:include, InstanceMethods)
+      target.extend ClassMethods
+    end
+
+    module InstanceMethods
+    end
+
+    module ClassMethods
+      attr_accessor :attributes_map
+      attr_accessor :to_one_associations
+      attr_accessor :to_many_associations
+
+      def attribute(name, options = {}, &block)
+        add_attribute(name, options, &block)
+      end
+
+      def has_one(name, options = {})
+        add_to_one_association(name, options)
+      end
+
+      def has_many(name, options = {})
+        add_to_many_association(name, options)
+      end
+
+      def add_attribute(name, options = {}, &block)
+        # Blocks are optional and can override the default attribute discovery. They are just
+        # stored here, but evaluated by the Serializer within the instance context.
+        @attributes_map ||= {}
+        @attributes_map[name] = {
+          attr_or_block: block_given? ? block : name,
+          options: options,
+        }
+      end
+      private :add_attribute
+
+      def add_to_one_association(name, options = {}, &block)
+        @to_one_associations ||= {}
+        @to_one_associations[name] = {
+          attr_or_block: block_given? ? block : name,
+          options: options,
+        }
+      end
+      private :add_to_one_association
+
+      def add_to_many_association(name, options = {}, &block)
+        @to_many_associations ||= {}
+        @to_many_associations[name] = {
+          attr_or_block: block_given? ? block : name,
+          options: options,
+        }
+      end
+      private :add_to_many_association
+    end
+  end
+end