http-api-tools 0.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    ZTExZDgwZjc0ZDQ3M2NiYjlhZDI2NGZlNWIxMWRiOGU2ZGI1MTlkNA==
+  data.tar.gz: !binary |-
+    YWU4ZTczYzliMjQwZjhjYWJhMDI0MTEzODlmZTIxM2I2ODhlNmVhYQ==
+SHA512:
+  metadata.gz: !binary |-
+    YzYxODgxNWEyY2YxYmY5MDVhOTdkNTgxNTdkZjUyNmIyOTM2YWJkOGJkNjRk
+    YTJiNTYwMzczM2U3NzNmZjczNzU1Y2E5MzczZDk2MDU3ODI5NGE4N2RkNWJi
+    YzdjOWI1YjdjYWViMWJjYzFiNTU4MzA0Nzg5MTQxMGRmODk2YmU=
+  data.tar.gz: !binary |-
+    ZDUyNmQ1YjYxYjI1YTgzN2E0ZjA3ZGI5ZjEzN2VkNTljODM4OTZlODE4M2Jj
+    MmM5MWUzM2EwZjk0ODM1YTU1MzlkMDEwYTQwNWZmNjZlZmUzZmVlMzQ0Nzc1
+    MmYwNDc1MDNmZDI4NTMxZmM3OTY1ZjRmZmRhZTQwOGVmYTJiNmU=

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+reports/profile_report.html

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format documentation
+--profile

data/Gemfile

@@ -0,0 +1,6 @@
+# encoding: utf-8
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in hat.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Hooroo
+
+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,485 @@
+## NOTE: Current WIP branch with a bunch of refactoring towards adding a nested serializer.
+
+-------------------------------------------------------------------------------------------
+Design notes for nested serializer:
+
+- The relation_sideloader should be able to become a more generic relation_loader that can support
+loading of both sideloaded and nested structures.
+
+
+
+
+# Http API Tools
+
+Provides fast serialization/deserialization of models with simple model attribute definition in client apps.
+
+Adheres to the ID Based Json API Spec - http://jsonapi.org/format/#id-based-json-api for serialization
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'hat'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install hat
+
+## Usage
+At a high level this gem provides serialization of models (active model or otherwise), deserialization of the serialized json and a way to declaritively create basic models in clients with basic type coercion.
+
+It has been written to work as a whole where the producer and client of the api are both maintained by the same development team. Conventions are used throughout to keep things simple. At this stage, breaking these conventions isn't supported in many cases but the gem can be extended towards this goal as the needs arise. Please see the note on performance in the section on contributing at the end of this document.
+
+### Serialization
+There are two supported serialization formats - sideloading and nesting. Both formats maintain an identical api and
+usage pattern while serializing in different ways. While it is possible to provide both formats in an application, it's likely you'd stick to one as the general philosophy is that a resource should always be represented in the same way.
+
+To use a serializer in a controller you should instantiate an instance of the serializer for the top level type you're serializing and pass it to render.
+
+`render json: UserSerializer.new(user)`
+
+
+#### Nesting vs Sideloading
+The big difference between these formats is that nesting represents the relationships between resources implicitly in it's structure whereas sideloading is a flattened structure with relationships represented via linked identifiers. The details of these formats will be described in more detail below.
+
+
+#### Serializer Definition
+
+This serializer will either be defined as a nesting or sideloading serializer depening on the serializer it is based on.
+
+```ruby
+class UserSerializer
+
+  include Hat::Sideloading::JsonSerializer
+
+end
+```
+
+```ruby
+class UserSerializer
+
+  include Hat::Nesting::JsonSerializer
+
+end
+
+
+Serializers can define attributes and relationships to be serialized.
+
+```ruby
+class UserSerializer
+
+  include Hat::Sideloading::JsonSerializer
+
+  serializes(User)
+  attributes :id, :first_name, :last_name
+  has_many :posts
+  has_one :profile
+
+end
+```
+
+If you want to serialize any composite attributes they can be defined as a method on the serializer and defined as an attribute. The object being serialized can be accessed via the `serializable` method on the serializer.
+
+```ruby
+class UserSerializer
+
+  include Hat::Sideloading::JsonSerializer
+
+  serializes(User)
+  attributes :id, :first_name, :last_name, :full_name
+
+  def full_name
+    "#{serializable.first_name} #{serializable.last_name}"
+  end
+
+end
+```
+
+#### JSON Structure
+
+##### Sideloading
+
+By default, only the ids of related objects will be serialized. For serializers using a 'sideloading' approach, these relationships and their ids will be added to the `links` hash.
+
+
+```javascript
+{
+ "users": [{
+    "id": 1,
+    "first_name": "John",
+    "last_name": "Smith",
+    "links" {
+      "profile": 2,
+      "posts": [3, 4]
+    }
+ }]
+}
+```
+
+##### Nesting
+As with sideloading serializers, by default, only the ids of related objects will be serialized. For serializers using a 'nesting' approach, these relationships and their ids will be inlined using their _id / _ids attribute name suffix.
+
+
+
+```javascript
+{
+ "users": [{
+    "id": 1,
+    "first_name": "John",
+    "last_name": "Smith",
+    "profile_id": 2,
+    "post_ids": [3, 4]
+ }]
+}
+```
+
+One advantage to this approach is that it's always clear what relationships exist for a resource, even if you don't
+include the resources themselves in the response.
+
+##### Serializing related resources via includes
+Often it will be desirable to load related data to save on requests. This can be done when creating the top level serializer using the same approach ActiveRecord uses for including relationships in queries.
+
+`UserSerializer.new(user).includes(:profile, { posts: [:comments] })`
+
+Which produces the following json when sideloaded:
+
+```javascript
+{
+ "users": [{
+    "id": 1,
+    "first_name": "John",
+    "last_name": "Smith",
+    "links": {
+      "profile": 2,
+      "posts": [3, 4]
+    }
+ }],
+ "linked": {
+   "profiles": [
+    {
+      "id": 2,
+      //...
+    }
+   ],
+
+   posts: [
+    {
+      "id": 3,
+      "links": {
+        "user": 1,
+        "comments": [5]
+      }
+      //...
+    },
+    {
+      "id": 4,
+      "links": {
+        "user": 1,
+        "comments": []
+      }
+      //...
+    }
+   ],
+   "comments": [
+    "id": 5,
+    "links": {
+        "post": 3
+    }
+    //...
+   ]
+  }
+
+}
+```
+
+and the following when nested:
+
+```javascript
+{
+ "users": [{
+    "id": 1,
+    "first_name": "John",
+    "last_name": "Smith",
+    "profile": {
+      "id": 2,
+    },
+    posts: [
+      {
+        "id": 3,
+        "user_id": 1
+        "comments": [
+          {
+            "id": 5,
+            "post_id": 3
+          }
+        ]
+      },
+      {
+        "id": 4,
+        "user_id": 1
+        "comments": []
+      }
+    ]
+  }]
+}
+
+One benefit to sideloading over nesting resources is that if the same resource is referenced multiple times, it only needs to be serialized once. Depending on your data, this may or may not be significant.
+
+##### Including related resources via the url
+It's possible to determine what resources to include by providing a query string parameter:
+
+`http://example.com/users/1?include?comments,posts.comments`
+
+This can be parsed using:
+
+`relation_includes = Hat::RelationIncludes.from_params(params)`
+
+and splat into the serializer includes:
+
+`UserSerializer.new(user).includes(*relation_includes)`
+
+and/or active record queries:
+
+`User.find(params[:id]).includes(*user_serializer.includes_for_query)`
+
+When providing the includes for an active record query, we actually want a deeper set of includes in order to account for the ids fetched for has_many relationships. If we passed the same set of includes to the query as we pass to the serializer, we'd end up with n+1 queries when fetching the ids for the has_many relationships.
+
+Calling `user_serializer.includes_for_query` will figure out the minimum set of includes that are required based on the following:
+
+* The models and their relationships
+* The relationships actually being serialized
+
+##### Restricting what is included
+Once you expose what can be included as a query string parameter you risk exposing too much information or poorly considered api calls that fetch too much. This can be countered by defining what is `includable` for each serializer when it's being used as the root serializer for a json response.
+
+```ruby
+class UserSerializer
+
+  include Hat::Nesting::JsonSerializer
+
+  serializes(User)
+
+  attributes :id, :first_name, :last_name, :full_name
+
+  has_many :posts
+  has_many :comments
+
+  includable(:profile, {:posts, [:comments]})
+
+end
+```
+
+This will ensure that regardless of what is declared in the `include` param, no more than the allowable includes are ever returned.
+
+To help in documenting what is includable, both the includable and included relations are returned in the meta data of the response.
+
+```javascript
+"meta": {
+  "type": "user",
+  "root_key": "users",
+  "includable": "profile,posts,posts.comments"
+  "included": "posts"
+}
+```
+
+#### Meta data
+Every request will also contain a special meta attribute which could be augmented with various additional pieces
+of meta-data. At this point, it will always return the `type` and `root_key` for the current request.  Eg:
+
+```javascript
+{
+  "meta": {
+    "type": "user",
+    "root_key": "users"
+  },
+  "users": [{
+    "id": 1,
+    "first_name": "John",
+    "last_name": "Smith",
+    "profile_id": 2,
+    "post_ids": [3, 4]
+  }]
+}
+```
+
+Notice that the root is an array and the root_key a plural. This is the case regardless of whether a single resource
+is being represented or a collection of resources. This is in line with the json-api spec and generally simplifies both serialization and deserialization.
+
+##### Adding Metadata
+It might be desirable to add extra metadata to the serialized response. For example, adding information such as limit, offset, what includes are valid etc can be helpful to a client.
+
+`UserSerializer.new(user).meta(limit: 10, offset: 0)`
+
+
+
+### Deserialization
+The `Hat::JsonDeserializer` expects json in the format that the serializer has created making it easy to create matching rest apis and clients with little work needing to be done at each end. Currently only sideloaded json can be deserialized. Nested deserializers are coming.
+
+`Hat::JsonDeserializer.new(json).deserialize`
+
+This will iterate over the json, using the attribute names to match types to models in the client app. As long as models exist with names that match the keys in the json, a complete graph of objects will be created upon deserialization, complete with two way relationships when they exist.
+
+In the previous example, the following model classes would be expected:
+
+* User
+* Post
+* Comment
+
+#### Deserializer Mappings
+
+At times, the name of an object's key may deviate from it's type and can't be deserialized by convention alone.
+
+```javascript
+{
+ "users": [{
+    "id": 1,
+    "first_name": "John",
+    "last_name": "Smith",
+    "links": {
+      "posts": [3]
+    }
+ }],
+ "linked": {
+   posts: [
+    {
+      "id": 3,
+      "links": {
+        "author": 1
+      }
+    }
+  }
+}
+```
+
+In this example, the `user` is the `author` of the `post`. It is impossible to infer from the data that an `author` attribute key should map to a `User` type so we need to give it a helping hand. This can be done once per type by creating a `JsonDeserializerMapping` class. Like with serializers, deserializer mappings are convention based, using the model class name as a prefix.
+
+```ruby
+class PostDeserializerMapping
+
+  include Hat::JsonDeserializerMapping
+
+  map :author, User
+
+end
+```
+
+Whenever we're deserializing a `post`, the `author` attribute will always be deserialized to an instance of a `User`.
+
+This can also be applied against collections:
+
+```ruby
+class CompanyDeserializerMapping
+
+  include Hat::JsonDeserializerMapping
+
+  map :employees, Person
+
+end
+```
+
+### Models
+Client models have some basic requirements that are catered to such as attribute definition, default values and type tranforms.
+
+For example:
+
+```ruby
+class User
+
+  include Hat::Model::Attributes
+  include Hat::Model::ActsLikeActiveModel
+
+  attribute :id
+  attribute :first_name
+  attribute :last_name
+  attribute :created_at: type: :date_time
+  attribute :posts, default: []
+  attribute :profile
+
+end
+```
+
+This will define a User class with attr_accessors for all attributes defined. The initialize method will accept a hash of values which will be passed through type transformers when configured and have defaults applied when no value is passed in for a key.
+
+Currently there is a single registered type transform for date_time transforms. This expects an iso8601 date format as a string which will be transformed into a ruby DateTime.
+
+#### Registering custom type transformers.
+
+Type transformers expect the following two-way interface:
+
+```ruby
+class MoneyTranformer
+
+  def self.from_raw(value)
+    Money.new(value)
+  end
+
+  def self.to_raw(money)
+    money.to_s
+  end
+
+end
+```
+
+Transformers should then be registered against a type key:
+
+
+```ruby
+Hat::Transformers::Registry.instance.register(:money, MoneyTransformer)
+```
+
+Now you can define an attribute as a `money` type:
+
+```ruby
+class Account
+
+  include Hat::Model::Attributes
+
+  attribute :balance: type: :money
+
+end
+```
+
+#### Read only attributes
+Sometimes it's useful to define a field as readonly. The intent being that we prevent changing an attribute value that shouldn't be changed or prevent a value from being serialized and sent in the payload that the server won't accept.
+
+In the previous example, it might be better to set the `created_at` field as readonly:
+
+```ruby
+class User
+
+  include Hat::Model::Attributes
+  include Hat::Model::ActsLikeActiveModel
+
+  attribute :id
+  attribute :first_name
+  attribute :last_name
+  attribute :created_at: type: :date_time, read_only: true
+  attribute :posts, default: []
+  attribute :profile
+
+end
+```
+
+### Polymorphism
+At this point, polymorphic relationships are not catered for but they can be when the need arises.
+
+
+## Contributing
+
+### A note on performance
+Performance is critial for this gem so any changes must be made with this in mind. There is a basic performance
+spec for serialization that dumps some timings and creates a profile report in `reports/profile_report.html`.
+
+Until we have a more robust way of tracking performance over time, please do some before and after tests against this when you make changes. Even small things have been found to introduce big performance issues.
+
+
+## To Do
+* Deserializer for nested json
+
+
+
+

data/Rakefile

@@ -0,0 +1,4 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+task :default => :spec
+RSpec::Core::RakeTask.new

data/http-api-tools.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'hat/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "http-api-tools"
+  spec.version       = Hat::VERSION
+  spec.authors       = ["Rob Monie"]
+  spec.email         = ["robmonie@gmail.com"]
+  spec.description   = %q{Http API Tools}
+  spec.summary       = %q{Provides JSON serialization/deserialization and basic model attribute definition for client apps}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  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_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "activesupport"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "pry-debugger"
+  spec.add_development_dependency "ruby-prof"
+
+end

data/lib/hat/base_json_serializer.rb

@@ -0,0 +1,107 @@
+
+require "active_support/core_ext/class/attribute"
+require "active_support/json"
+require 'active_support/core_ext/string/inflections'
+require_relative 'relation_includes'
+require_relative 'identity_map'
+require_relative 'type_key_resolver'
+
+module Hat
+  module BaseJsonSerializer
+
+    attr_reader :serializable, :relation_includes, :result, :meta_data
+
+    def initialize(serializable, attrs = {})
+      @serializable = serializable
+      @relation_includes = attrs[:relation_includes] || RelationIncludes.new
+      @result = attrs[:result] || {}
+      @meta_data = { type: root_key.to_s.singularize, root_key: root_key.to_s }
+    end
+
+
+    def attribute_hash
+
+      attribute_hash = {}
+
+      attributes.each do |attr_name|
+        if self.respond_to?(attr_name)
+          attribute_hash[attr_name] = self.send(attr_name)
+        else
+          attribute_hash[attr_name] = serializable.send(attr_name)
+        end
+      end
+
+      attribute_hash
+
+    end
+
+
+    def to_json(*args)
+      JSON.fast_generate(as_json)
+    end
+
+    def includes(*includes)
+
+      if includable
+        allowable_includes_to_add = RelationIncludes.new(*includes) & includable
+      else
+        allowable_includes_to_add = includes
+      end
+
+      relation_includes.include(allowable_includes_to_add)
+
+      self
+    end
+
+    def meta(data)
+      meta_data.merge!(data)
+      self
+    end
+
+    def attributes
+      self.class._attributes
+    end
+
+    def has_ones
+      self.class.has_ones
+    end
+
+    def has_manys
+      self.class.has_manys
+    end
+
+    def includable
+      self.class._includable
+    end
+
+    def includes_for_query
+      RelationIncludes.new(*ExpandedRelationIncludes.new(relation_includes, self))
+    end
+
+    protected
+
+    attr_accessor :identity_map
+
+    private
+
+    attr_writer :relation_includes
+    attr_reader :type_key_resolver
+    attr_accessor :serializer_map, :meta_data
+
+    def root_key
+      @_root_key ||= self.class._serializes.name.split("::").last.underscore.pluralize.to_sym
+    end
+
+    def includes_meta_data
+      {
+        includable: includable.to_s.blank? ? '*' : includable.to_s,
+        included: relation_includes.to_s
+      }
+    end
+
+    def assert_id_present(serializable_item)
+      raise "serializable items must have an id attribute" unless serializable_item.respond_to?(:id)
+    end
+
+  end
+end