active_model_serializers 0.8.3 → 0.10.0.rc5

data/docs/howto/add_pagination_links.md

@@ -0,0 +1,139 @@
+[Back to Guides](../README.md)
+
+# How to add pagination links
+
+### JSON API adapter
+
+Pagination links will be included in your response automatically as long as
+the resource is paginated and if you are using the ```JsonApi``` adapter.
+
+If you want pagination links in your response, use [Kaminari](https://github.com/amatsuda/kaminari)
+or [WillPaginate](https://github.com/mislav/will_paginate).
+
+Although the others adapters does not have this feature, it is possible to
+implement pagination links to `JSON` adapter. For more information about it,
+please see in our docs 
+
+###### Kaminari examples
+
+```ruby
+#array
+@posts = Kaminari.paginate_array([1, 2, 3]).page(3).per(1)
+render json: @posts
+
+#active_record
+@posts = Post.page(3).per(1)
+render json: @posts
+```
+
+###### WillPaginate examples
+
+```ruby
+#array
+@posts = [1,2,3].paginate(page: 3, per_page: 1)
+render json: @posts
+
+#active_record
+@posts = Post.page(3).per_page(1)
+render json: @posts
+```
+
+```ruby
+ActiveModelSerializers.config.adapter = :json_api
+```
+
+ex:
+```json
+{
+  "data": [
+    {
+      "type": "articles",
+      "id": "3",
+      "attributes": {
+        "title": "JSON API paints my bikeshed!",
+        "body": "The shortest article. Ever.",
+        "created": "2015-05-22T14:56:29.000Z",
+        "updated": "2015-05-22T14:56:28.000Z"
+      }
+    }
+  ],
+  "links": {
+    "self": "http://example.com/articles?page[number]=3&page[size]=1",
+    "first": "http://example.com/articles?page[number]=1&page[size]=1",
+    "prev": "http://example.com/articles?page[number]=2&page[size]=1",
+    "next": "http://example.com/articles?page[number]=4&page[size]=1",
+    "last": "http://example.com/articles?page[number]=13&page[size]=1"
+  }
+}
+```
+
+ActiveModelSerializers pagination relies on a paginated collection with the methods `current_page`, `total_pages`, and `size`, such as are supported by both [Kaminari](https://github.com/amatsuda/kaminari) or [WillPaginate](https://github.com/mislav/will_paginate).
+
+
+### JSON adapter
+
+If you are using `JSON` adapter, pagination links will not be included automatically, but it is possible to do so using `meta` key.
+
+Add this method to your base API controller.
+
+```ruby
+def pagination_dict(object)
+  {
+    current_page: object.current_page,
+    next_page: object.next_page,
+    prev_page: object.prev_page,
+    total_pages: object.total_pages,
+    total_count: object.total_count
+  }
+end
+```
+
+Then, use it on your render method.
+
+```ruby
+render json: posts, meta: pagination_dict(posts)
+```
+
+ex.
+```json
+{
+  "posts": [
+    {
+      "id": 2,
+      "title": "JSON API paints my bikeshed!",
+      "body": "The shortest article. Ever."
+    }
+  ],
+  "meta": {
+    "current_page": 3,
+    "next_page": 4,
+    "prev_page": 2,
+    "total_pages": 10,
+    "total_count": 10
+  }
+}
+```
+
+You can also achieve the same result if you have a helper method that adds the pagination info in the meta tag. For instance, in your action specify a custom serializer.
+
+```ruby
+render json: @posts, each_serializer: PostPreviewSerializer, meta: meta_attributes(@post)
+```
+
+```ruby
+#expects pagination!
+def meta_attributes(resource, extra_meta = {})
+  {
+    current_page: resource.current_page,
+    next_page: resource.next_page,
+    prev_page: resource.prev_page,
+    total_pages: resource.total_pages,
+    total_count: resource.total_count
+  }.merge(extra_meta)
+end
+```
+
+
+### Attributes adapter
+
+This adapter does not allow us to use `meta` key, due to that it is not possible to add pagination links.

data/docs/howto/add_root_key.md

@@ -0,0 +1,51 @@
+# How to add root key
+
+Add the root key to your API is quite simple with ActiveModelSerializers. The **Adapter** is what determines the format of your JSON response. The default adapter is the ```Attributes``` which doesn't have the root key, so your response is something similar to:
+
+```json
+{
+  "id": 1,
+  "title": "Awesome Post Tile",
+  "content": "Post content"
+}
+```
+
+In order to add the root key you need to use the ```JSON``` Adapter, you can change this in an initializer:
+
+```ruby
+ActiveModelSerializers.config.adapter = :json
+```
+
+You can also specify a class as adapter, as long as it complies with the ActiveModelSerializers adapters interface.
+It will add the root key to all your serialized endpoints.
+
+ex:
+
+```json
+{
+  "post": {
+    "id": 1,
+    "title": "Awesome Post Tile",
+    "content": "Post content"
+  }
+}
+```
+
+or if it returns a collection:
+
+```json
+{
+  "posts": [
+    {
+      "id": 1,
+      "title": "Awesome Post Tile",
+      "content": "Post content"
+    },
+    {
+      "id": 2,
+      "title": "Another Post Tile",
+      "content": "Another post content"
+    }
+  ]
+}
+```

data/docs/howto/outside_controller_use.md

@@ -0,0 +1,58 @@
+[Back to Guides](../README.md)
+
+## Using ActiveModelSerializers Outside Of A Controller
+
+### Serializing a resource
+
+In ActiveModelSerializers versions 0.10 or later, serializing resources outside of the controller context is fairly simple:
+
+```ruby
+# Create our resource
+post = Post.create(title: "Sample post", body: "I love Active Model Serializers!")
+
+# Optional options parameters
+options = {}
+
+# Create a serializable resource instance
+serializable_resource = ActiveModelSerializers::SerializableResource.new(post, options)
+
+# Convert your resource into json
+model_json = serializable_resource.as_json
+```
+
+### Looking up the Serializer for a Resource
+
+If you want to retrieve a serializer for a specific resource, you can do the following:
+
+```ruby
+# Create our resource
+post = Post.create(title: "Another Example", body: "So much fun.")
+
+# Optional options parameters
+options = {}
+
+# Retrieve the default serializer for posts
+serializer = ActiveModel::Serializer.serializer_for(post, options)
+```
+
+You could also retrieve the serializer via:
+
+```ruby
+ActiveModelSerializers::SerializableResource.new(post, options).serializer
+```
+
+Both approaches will return an instance, if any, of the resource's serializer.
+
+## Serializing before controller render
+
+At times, you might want to use a serializer without rendering it to the view. For those cases, you can create an instance of `ActiveModelSerializers::SerializableResource` with
+the resource you want to be serialized and call `.as_json`.
+
+```ruby
+def create
+  message = current_user.messages.create!(message_params)
+  message_json = ActiveModelSerializers::SerializableResource.new(message).as_json
+  MessageCreationWorker.perform(message_json)
+  head 204
+end
+```

data/docs/howto/passing_arbitrary_options.md

@@ -0,0 +1,27 @@
+[Back to Guides](../README.md)
+
+# Passing Arbitrary Options To A Serializer
+
+In addition to the [`serialization_scope`](../general/serializers.md#scope), any options passed to `render`
+that are not reserved for the [adapter](../general/rendering.md#adapter_opts)
+are available in the serializer as [instance_options](../general/serializers.md#instance_options).
+
+For example, we could pass in a field, such as `user_id` into our serializer.
+
+```ruby
+# posts_controller.rb
+class PostsController < ApplicationController
+  def dashboard  
+    render json: @post, user_id: 12
+  end
+end
+
+# post_serializer.rb
+class PostSerializer < ActiveModel::Serializer
+  attributes :id, :title, :body
+
+  def comments_by_me  
+    Comments.where(user_id: instance_options[:user_id], post_id: object.id)
+  end
+end
+```

data/docs/howto/test.md

@@ -0,0 +1,152 @@
+# How to test
+
+## Controller Serializer Usage
+
+ActiveModelSerializers provides a `assert_serializer` method to be used on your controller tests to
+assert that a specific serializer was used.
+
+```ruby
+class PostsControllerTest < ActionController::TestCase
+  test "should render post serializer" do
+    get :index
+    assert_serializer "PostSerializer"
+  end
+end
+```
+
+See [ActiveModelSerializers::Test::Serializer](../../lib/active_model_serializers/test/serializer.rb)
+for more examples and documentation.
+
+## Serialization against a schema
+
+### Dependencies
+
+To use the `assert_response_schema` you need to have the
+[`json_schema`](https://github.com/brandur/json_schema) on your Gemfile. Please
+add it to your Gemfile and run `$ bundle install`.
+
+### Minitest test helpers
+
+ActiveModelSerializers provides a `assert_response_schema` method to be used on your controller tests to
+assert the response against a [JSON Schema](http://json-schema.org/). Let's take
+a look in an example.
+
+```ruby
+class PostsController < ApplicationController
+  def show
+    @post = Post.find(params[:id])
+
+    render json: @post
+  end
+end
+```
+
+To test the `posts#show` response of this controller we need to create a file
+named `test/support/schemas/posts/show.json`. The helper uses a naming convention
+to locate the file.
+
+This file is a JSON Schema representation of our response.
+
+```json
+{
+  "properties": {
+    "title" : { "type" : "string" },
+    "content" : { "type" : "string" }
+  }
+}
+```
+
+With all in place we can go to our test and use the helper.
+
+```ruby
+class PostsControllerTest < ActionController::TestCase
+  test "should render right response" do
+    get :index
+    assert_response_schema
+  end
+end
+```
+
+#### Load a custom schema
+
+If we need to use another schema, for example when we have a namespaced API that
+shows the same response, we can pass the path of the schema.
+
+```ruby
+module V1
+  class PostsController < ApplicationController
+    def show
+      @post = Post.find(params[:id])
+
+      render json: @post
+    end
+  end
+end
+```
+
+```ruby
+class V1::PostsControllerTest < ActionController::TestCase
+  test "should render right response" do
+    get :index
+    assert_response_schema('posts/show.json')
+  end
+end
+```
+
+#### Change the schema path
+
+By default all schemas are created at `test/support/schemas`. If we are using
+RSpec for example we can change this to `spec/support/schemas` defining the
+default schema path in an initializer.
+
+```ruby
+ActiveModelSerializers.config.schema_path = 'spec/support/schemas'
+```
+
+#### Using with the Heroku’s JSON Schema-based tools
+
+To use the test helper with the [prmd](https://github.com/interagent/prmd) and
+[committee](https://github.com/interagent/committee).
+
+We need to change the schema path to the recommended by prmd:
+
+```ruby
+ActiveModelSerializers.config.schema_path = 'docs/schema/schemata'
+```
+
+We also need to structure our schemata according to Heroku's conventions
+(e.g. including
+[required metadata](https://github.com/interagent/prmd/blob/master/docs/schemata.md#meta-data)
+and [links](https://github.com/interagent/prmd/blob/master/docs/schemata.md#links).
+
+#### JSON Pointers
+
+If we plan to use [JSON
+Pointers](http://spacetelescope.github.io/understanding-json-schema/UnderstandingJSONSchema.pdf) we need to define the `id` attribute on the schema. Example:
+
+```js
+// attributes.json
+
+{
+  "id": "file://attributes.json#",
+  "properties": {
+    "name" : { "type" : "string" },
+    "description" : { "type" : "string" }
+  }
+}
+```
+
+```js
+// show.json
+
+{
+  "properties": {
+    "name": {
+      "$ref": "file://attributes.json#/properties/name"
+    },
+    "description": {
+      "$ref": "file://attributes.json#/properties/description"
+    }
+  }
+}
+```

data/docs/integrations/ember-and-json-api.md

@@ -0,0 +1,112 @@
+[Back to Guides](../README.md)
+
+# Integrating with Ember and JSON API
+
+ - [Preparation](./ember-and-json-api.md#preparation)
+ - [Server-Side Changes](./ember-and-json-api.md#server-side-changes)
+ - [Adapter Changes](./ember-and-json-api.md#adapter-changes)
+   - [Serializer Changes](./ember-and-json-api.md#serializer-changes)
+ - [Including Nested Resources](./ember-and-json-api.md#including-nested-resources)
+
+## Preparation
+
+Note: This guide assumes that `ember-cli` is used for your ember app.
+
+The JSON API specification calls for hyphens for multi-word separators. ActiveModelSerializers uses underscores.
+To solve this, in Ember, both the adapter and the serializer will need some modifications:
+
+### Server-Side Changes
+
+there are multiple mimetypes for json that should all be parsed similarly, so
+in `config/initializers/mime_types.rb`:
+```ruby
+api_mime_types = %W(
+  application/vnd.api+json
+  text/x-json
+  application/json
+)
+
+Mime::Type.unregister :json
+Mime::Type.register 'application/json', :json, api_mime_types
+```
+
+### Adapter Changes
+
+```javascript
+// app/adapters/application.js
+import DS from 'ember-data';
+import ENV from "../config/environment";
+
+export default  DS.JSONAPIAdapter.extend({
+  namespace: 'api',
+  // if your rails app is on a different port from your ember app
+  // this can be helpful for development.
+  // in production, the host for both rails and ember should be the same.
+  host: ENV.host,
+
+  // allows the multiword paths in urls to be underscored
+  pathForType: function(type) {
+    let underscored = Ember.String.underscore(type);
+    return Ember.String.pluralize(underscored);
+  },
+
+  // allows queries to be sent along with a findRecord
+  // hopefully Ember / EmberData will soon have this built in
+  // ember-data issue tracked here:
+  // https://github.com/emberjs/data/issues/3596
+  urlForFindRecord(id, modelName, snapshot) {
+    let url = this._super(...arguments);
+    let query = Ember.get(snapshot, 'adapterOptions.query');
+    if(query) {
+      url += '?' + Ember.$.param(query);
+    }
+    return url;
+  }
+});
+```
+
+### Serializer Changes
+
+```javascript
+// app/serializers/application.js
+import Ember from 'ember';
+import DS from 'ember-data';
+var underscore = Ember.String.underscore;
+
+export default DS.JSONAPISerializer.extend({
+  keyForAttribute: function(attr) {
+    return underscore(attr);
+  },
+
+  keyForRelationship: function(rawKey) {
+    return underscore(rawKey);
+  }
+});
+
+```
+
+## Including Nested Resources
+
+Previously, `store.find` and `store.findRecord` did not allow specification of any query params.
+The ActiveModelSerializers default for the `include` parameter is to be `nil` meaning that if any associations are defined in your serializer, only the `id` and `type` will be in the `relationships` structure of the JSON API response.
+For more on `include` usage, see: [The JSON API include examples](./../general/adapters.md#JSON-API)
+
+With the above modifications, you can execute code as below in order to include nested resources while doing a find query.
+
+```javascript
+store.findRecord('post', postId, { adapterOptions: { query: { include: 'comments' } } });
+```
+will generate the path `/posts/{postId}?include='comments'`
+
+So then in your controller, you'll want to be sure to have something like:
+```ruby
+render json: @post, include: params[:include]
+```
+
+If you want to use `include` on a collection, you'd write something like this:
+
+```javascript
+store.query('post', { include: 'comments' });
+```
+
+which will generate the path `/posts?include='comments'`

data/docs/integrations/grape.md

@@ -0,0 +1,19 @@
+# Integration with Grape
+
+[Grape](https://github.com/ruby-grape/grape) is an opinionated micro-framework for creating REST-like APIs in ruby.
+
+ActiveModelSerializers currently supports Grape >= 0.13, < 1.0
+
+To add [Grape](https://github.com/ruby-grape/grape) support, enable the formatter and helper functions by including `Grape::ActiveModelSerializers` in your base endpoint. For example:
+
+```ruby
+module Example
+  class Dummy < Grape::API
+    require 'grape/active_model_serializers'
+    include Grape::ActiveModelSerializers
+    mount Example::V1::Base
+  end
+end
+```
+
+Aside from this, [configuration](../general/configuration_options.md) of ActiveModelSerializers is exactly the same.

data/docs/jsonapi/errors.md

@@ -0,0 +1,56 @@
+[Back to Guides](../README.md)
+
+# [JSON API Errors](http://jsonapi.org/format/#errors)
+
+Rendering error documents requires specifying the error serializer(s):
+
+- Serializer:
+  - For a single resource: `serializer: ActiveModel::Serializer::ErrorSerializer`.
+  - For a collection: `serializer: ActiveModel::Serializer::ErrorsSerializer`, `each_serializer: ActiveModel::Serializer::ErrorSerializer`.
+
+The resource **MUST** have a non-empty associated `#errors` object.
+The `errors` object must have a `#messages` method that returns a hash of error name to array of
+descriptions.
+
+## Use in controllers
+
+```ruby
+resource = Profile.new(name: 'Name 1',
+                       description: 'Description 1',
+                       comments: 'Comments 1')
+resource.errors.add(:name, 'cannot be nil')
+resource.errors.add(:name, 'must be longer')
+resource.errors.add(:id, 'must be a uuid')
+
+render json: resource, status: 422, adapter: :json_api, serializer: ActiveModel::Serializer::ErrorSerializer
+# #=>
+#  { :errors =>
+#    [
+#      { :source => { :pointer => '/data/attributes/name' }, :detail => 'cannot be nil' },
+#      { :source => { :pointer => '/data/attributes/name' }, :detail => 'must be longer' },
+#      { :source => { :pointer => '/data/attributes/id' }, :detail => 'must be a uuid' }
+#    ]
+#  }.to_json
+```
+
+## Direct error document generation
+
+```ruby
+options = nil
+resource = ModelWithErrors.new
+resource.errors.add(:name, 'must be awesome')
+
+serializable_resource = ActiveModelSerializers::SerializableResource.new(
+  resource, {
+    serializer: ActiveModel::Serializer::ErrorSerializer,
+    adapter: :json_api
+  })
+serializable_resource.as_json(options)
+# #=>
+# {
+#   :errors =>
+#     [
+#       { :source => { :pointer => '/data/attributes/name' }, :detail => 'must be awesome' }
+#     ]
+# }
+```