jei 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ea19615f8a84331de1de9c82554319903558736d
-  data.tar.gz: 10de19e392712355a970f2696f4e241f8937828e
+  metadata.gz: 7bf0d7bbd5077695a2e1219961576f894a5cd41f
+  data.tar.gz: 34cb6f17efada6cd82e01d23e8e67a16f7f2414e
 SHA512:
-  metadata.gz: aa5ce85017fe71e8552c92362a71bfcf548516a80fab884bbcb752174b2e6b7aac897f75f92643db3db39ec8b42afa93559849bc466cc4c9bb43dae27e330f25
-  data.tar.gz: 683c3c1b22720d0d1dc0ce20ead770d60664d62dc226c0ad29cf76ccb322d4fbf8477d8ea66eff557d3b228d7a863c661914a11cc77b8aa48f7bdfd621f8cc36
+  metadata.gz: 89a27cbfe0af409953efaf4da6d83f7a8f78659bf2ca58a40a22a1b148d8df1eb9d48a2b65e76f374b38598618a2fcf8310b425d001977ef0580a2a3186ed59b
+  data.tar.gz: 5972dc16d4c2df09654730607ffbfa92165751a12fc3c6284923b4516af448c987e2b7747f99c4d39bf7266bfb09a5915b0bec0b2496685049bd5388c78764e3

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## HEAD
+
+## 0.2.0 (2016-03-22)
+
+* [ADD] Add `:fields` document build option for sparse fieldsets.
+* [BREAKING] A relationship links `Proc` is no longer passed the context as
+  an argument. Update usages of `links: ->(_) {}` to `links: -> {}`.
+* [ADD] Raise `Jei::Path::NameError` on bad relationship names.
+* [BREAKING] Rename relationship option `no_data` to `data`. Take the
+  inverse of each occurance to update, e.g., change `no_data: true` to
+  `data: false`.
+* [ADD] Add `:serializer` option to relationships to override the default
+  serializer class used.
+* [CHANGE] Serializers are compared via a `(type, id)` tuple rather than
+  object identity.
+* [FIX] Fix include usage when serializing a collection.
+
+## 0.1.0 (2016-03-15)
+
+* Initial release

data/README.md

@@ -17,6 +17,7 @@ install it manually.
 ```ruby
 require 'jei'
 
+# Create resource serializers.
 class ArtistSerializer < Jei::Serializer
   attribute :name
   has_many :albums
@@ -26,18 +27,15 @@ class AlbumSerializer < Jei::Serializer
   belongs_to :artist
 end
 
-class Artist < OpenStruct; end
-class Album < OpenStruct; end
-
 artist = Artist.new(id: 1, name: 'FIESTAR', albums: [])
-2.times { |i| artist.albums << Album.new(id: i + 1) }
+artist.albums << Album.new(id: 1, artist: artist)
+artist.albums << Album.new(id: 2, artist: artist)
 
+# Build a JSON API document from the resource.
 document = Jei::Document.build(artist)
 document.to_json
 ```
 
-This emits
-
 ```json
 {
   "data": {
@@ -57,3 +55,473 @@ This emits
   }
 }
 ```
+
+### Serializers
+
+A `Serializer` defines what attributes and relationships are serialized in a
+document.
+
+Jei uses reflection to automatically find the correct serailizer for a
+resource. To do this, create a class that extends `Jei::Serializer` and name it
+`#{resource.class.name}Serializer`. For example, an `Artist` resource would
+have a matching serializer named `ArtistSerializer` in the global namespace.
+
+```ruby
+class Artist; end
+class ArtistSerializer < Jei::Serializer; end
+```
+
+#### Attributes
+
+Attributes represent model data. They are defined in a serializer by using the
+`attribute` or `attributes` methods.
+
+```ruby
+class AlbumSerializer < Jei::Serializer
+  # Attributes can be listed by name. Each name is used as an attribute key
+  # and its value is invoked by its name on the resource.
+  attributes :kind, :name
+
+  # Attributes can also be added individually.
+  attribute :released_on
+
+  # This is useful because `attribute` optionally takes a block. It can be
+  # used to rename an attribute in the document when the resource responds to
+  # a different name.
+  attribute(:release_date) { resource.released_on }
+
+  # Or it can be use to create entirely new attributes and values.
+  attribute :formatted_name do
+    date = resource.released_on.strftime('%Y.%m.%d')
+    "[#{date}] #{resource.name}"
+  end
+end
+
+album = Album.new(id: 1, kind: :ep, name: 'A Delicate Sense', released_on: Date.new(2016, 3, 9))
+Jei::Document.build(album).to_json
+```
+
+```json
+{
+  "data": {
+    "id": "1",
+    "type": "albums",
+    "attributes": {
+      "kind": "ep",
+      "name": "A Delicate Sense",
+      "released_on": "2016-03-09",
+      "release_date": "2016-03-09",
+      "formatted_name": "[2016.03.09] A Delicate Sense"
+    }
+  }
+}
+```
+
+#### Relationships
+
+Relationships describe how the primary resource relates to other resources. A
+one-to-one relationship is defined by the `belongs_to` method, and a
+one-to-many relationship, `has_many`.
+
+The relationship names are invoked on the resource. A
+belongs-to relationship returns a single resource, whereas has-many returns a
+collection.
+
+```ruby
+class AlbumSerializer < Jei::Serializer
+  belongs_to :artist
+  has_many :tracks
+
+  # Like attributes, relationships can also take a block to override its value.
+  has_many :even_tracks do
+    resource.tracks.select { |t| t.id.even? }
+  end
+end
+
+class ArtistSerializer < Jei::Serializer; end
+class TrackSerializer < Jei::Serializer; end
+
+artist = Artist.new(id: 1)
+tracks = [Track.new(id: 1), Track.new(id: 2)]
+album = Album.new(id: 1, artist: artist, tracks: tracks)
+
+Jei::Document.build(album).to_json
+```
+
+```json
+{
+  "data": {
+    "id": "1",
+    "type": "albums",
+    "relationships": {
+      "artist": {
+        "data": { "id": "1", "type": "artists" }
+      },
+      "tracks": {
+        "data": [
+          { "id": "1", "type": "tracks" },
+          { "id": "2", "type": "tracks" }
+        ]
+      },
+      "even_tracks": {
+        "data": [
+          { "id": "2", "type": "tracks" }
+        ]
+      }
+    }
+  }
+}
+```
+
+##### Options
+
+Each relationship object can be modified with the following options.
+
+* `data`: (`Boolean`; default: `true`) Setting this to `false` supresses
+  building a data object with resource identifiers. Note that doing so does not
+  emit a valid JSON API document unless a links or meta object is present.
+
+    ```ruby
+    class ArtistSerializer < Jei::Serializer
+      has_many :albums, data: false
+    end
+
+    albums = [Album.new(id: 1), Album.new(id: 2)]
+    artist = Artist.new(id: 1, albums: albums)
+
+    Jei::Document.build(artist).to_json
+    ```
+
+    ```json
+    {
+      "data": {
+        "id": "1",
+        "type": "artists",
+        "relationships": {
+          "albums": {}
+        }
+      }
+    }
+    ```
+
+* `links`: (`Proc -> Array<Jei::Link>`) This is for relationship level links.
+  The `Proc` must return a list of `Link`s and is run in the context of the
+  serializer.
+
+    ```ruby
+    class ArtistSerializer < Jei::Serializer
+      has_many :albums, links: -> {
+        [Jei::Link.new(:related, "/#{type}/#{id}/albums")]
+      }
+    end
+
+    class AlbumSerializer < Jei::Serializer; end
+
+    albums = [Album.new(id: 1), Album.new(id: 2)]
+    artist = Artist.new(id: 1, albums: albums)
+    Jei::Document.build(artist).to_json
+    ```
+
+    ```json
+    {
+      "data": {
+        "id": "1",
+        "type": "artists",
+        "relationships": {
+          "albums": {
+            "data": [
+              { "id": "1", "type": "albums" },
+              { "id": "2", "type": "albums" }
+            ],
+            "links": {
+              "related": "/artists/1/albums"
+            }
+          }
+        }
+      }
+    }
+    ```
+
+* `serializer`: (`Class`) Overrides the default serializer used for each
+  related resource.
+
+    ```ruby
+    class RecordSerializer < Jei::Serializer
+      def type
+        'records'
+      end
+    end
+
+    class ArtistSerializer < Jei::Serializer
+      has_many :albums, serializer: RecordSerializer
+    end
+
+    artist = Artist.new(id: 1, albums: [Album.new(id: 1)])
+    Jei::Document.build(artist).to_json
+    ```
+
+    ```json
+    {
+      "data": {
+        "id": "1",
+        "type": "artists",
+        "relationships": {
+          "albums": {
+            "data": [
+              { "id": "1", "type": "records" }
+            ]
+          }
+        }
+      }
+    }
+    ```
+
+### Document
+
+As seen in previous examples, `Jei::Document` represents a JSON API document.
+After building the structure from a resource or collection of resources using
+`Document.build`, it can be serialized to a Ruby hash (`#to_h`) or a JSON
+string (`#to_json`).
+
+#### Options
+
+Top level objects can be added using the following options.
+
+* `:fields`: (`Hash<String, String>`) A map of resource type-fields that define
+  sparse fieldsets. Keys are resource types, and fields are a comma-separated
+  list of field names. For example, `{ 'artists' => 'name,albums', 'albums' =>
+  'released_on' }`.
+
+    ```ruby
+    class ArtistSerializer < Jei::Serializer
+      attributes :kind, :name
+      has_many :albums
+    end
+
+    artist = Artist.new(id: 1, kind: :group, name: 'FIESTAR', albums: [])
+
+    Jei::Document.build(artist, fields: { 'artists' => 'name' }).to_json
+    ```
+
+    ```json
+    {
+      "data": {
+        "id": "1",
+        "type": "artists",
+        "attributes": {
+          "name": "FIESTAR"
+        }
+      }
+    }
+    ```
+
+* `:include`: (`String`) A comma separated list of relationship paths. Each
+  path is a list of relationship names, separated by a period. For example, a
+  valid list of paths would be `artist,tracks.song`. The set of resources are
+  all unique resources on the include path.
+
+    ```ruby
+    class ArtistSerializer < Jei::Serializer
+      attribute :name
+      has_many :albums
+    end
+
+    class AlbumSerializer < Jei::Serializer
+      attributes :name, :release_date
+      belongs_to :artist
+      has_many :tracks
+    end
+
+    class TrackSerializer < Jei::Serializer
+      attributes :position, :name
+      belongs_to :album
+    end
+
+    artist = Artist.new(id: 1, name: 'FIESTAR')
+    album1 = Album.new(id: 1, name: 'A Delicate Sense', release_date: '2016-03-09', artist: artist)
+    album2 = Album.new(id: 2, name: 'Black Label', release_date: '2015-03-04', artist: artist)
+    artist.albums = [album1, album2]
+    album1.tracks = [Track.new(id: 1, position: 2, name: 'Mirror', album: album1)]
+    album2.tracks = [Track.new(id: 2, position: 1, name: "You're Pitiful", album: album2)]
+
+    Jei::Document.build(artist, include: 'albums.tracks').to_json
+    ```
+
+    ```json
+    {
+      "data": {
+        "id": "1",
+        "type": "artists",
+        "attributes": {
+          "name": "FIESTAR"
+        },
+        "relationships": {
+          "albums": {
+            "data": [
+              { "id": "1", "type": "albums" },
+              { "id": "2", "type": "albums" }
+            ]
+          }
+        }
+      },
+      "included": [
+        {
+          "id": "1",
+          "type": "albums",
+          "attributes": {
+            "name": "A Delicate Sense",
+            "release_date": "2016-03-09"
+          },
+          "relationships": {
+            "artist": {
+              "data": { "id": "1", "type": "artists" }
+            },
+            "tracks": {
+              "data": [
+                { "id": "1", "type": "tracks" }
+              ]
+            }
+          }
+        },
+        // ...
+      ]
+    }
+    ```
+
+* `:jsonapi`: (`Boolean`) Includes a JSON API object in top level of the
+  document.
+
+    ```ruby
+    Jei::Document.build(nil, jsonapi: true).to_json
+    ```
+
+    ```json
+    {
+      "jsonapi": {
+        "version": "1.0"
+      },
+      "data": null
+    }
+    ```
+
+* `:links`: (`Array<Link>`) Includes a links object in the top level of the
+  document.
+
+    ```ruby
+    links = [
+      Jei::Link.new(:self, '/artists?page[number]=2'),
+      Jei::Link.new(:prev, '/artists?page[number]=1'),
+      Jei::Link.new(:next, '/artists?page[number]=3')
+    ]
+    Jei::Document.build(nil, links: links).to_json
+    ```
+
+    ```json
+    {
+      "links": {
+        "self": "/artists?page[number]=2",
+        "prev": "/artists?page[number]=1",
+        "next": "/artists?page[number]=3"
+      },
+      "data": null
+    }
+    ```
+
+* `:meta`: (`Hash<Symbol, Object>`) Includes a meta object in the top level of
+  the document.
+
+    ```ruby
+    Jei::Document.build(nil, meta: { total_pages: 10 }).to_json
+    ```
+
+    ```json
+    {
+      "meta": {
+        "total_pages": 10
+      },
+      "data": null
+    }
+    ```
+
+* `:serializer`: (`Class`) Overrides the default serializer used for the
+  primary resource.
+
+    ```ruby
+    class SimpleArtistSerializer < Jei::Serializer
+      attribute :name
+    end
+
+    artist = Artist.new(id: 1, name: 'FIESTAR')
+    Jei::Document.build(artist, serializer: SimpleArtistSerializer).to_json
+    ```
+
+    ```json
+    {
+      "data": {
+        "id": "1",
+        "type": "artists",
+        "attributes": {
+          "name": "FIESTAR"
+        }
+      }
+    }
+    ```
+
+## Integration
+
+Jei is not tied to any framework and can be integrated as a normal gem.
+
+### Rails
+
+The simplest usage with [Rails][rails] is to define a new renderer.
+
+```ruby
+# config/initializers/jei.rb
+ActionController::Renderers.add(:jsonapi) do |resource, options|
+  document = Jei::Document.build(resource, options)
+  json = document.to_json
+  self.content_type = Mime::Type.lookup_by_extension(:jsonapi)
+  self.response_body = json
+end
+
+# config/initializers/mime_types.rb
+Mime::Type.register 'application/vnd.api+json', :jsonapi
+```
+
+Serializers can be placed in `app/serializers`. Include Rails' url helpers to
+have them conveniently accessible in the serializer context for links.
+
+```ruby
+# app/serializers/application_serializer.rb
+class ApplicationSerializer < Jei::Serializer
+  include Rails.application.routes.url_helpers
+end
+
+# app/serializers/album_serializer.rb
+class AlbumSerializer < ApplicationSerializer
+  attributes :kind, :name, :release_date
+  belongs_to :artist
+end
+
+# app/serializers/artist_serializer.rb
+class ArtistSerializer < ApplicationSerializer
+  attributes :name
+  has_many :albums, data: false, links: -> {
+    [Jei::Link.new(:related, album_path(resource))]
+  }
+end
+```
+
+Specify the `jsonapi` format defined earlier when rendering in a controller.
+
+```ruby
+# app/controllers/artists_controller.rb
+class ArtistsController < ApplicationController
+  def show
+    artist = Artist.find(params[:id])
+    render jsonapi: artist, include: params[:include]
+  end
+end
+```
+
+[rails]: http://rubyonrails.org/