diff --git a/docs/general/adapters.md b/docs/general/adapters.md new file mode 100644 index 000000000..a84fc4d31 --- /dev/null +++ b/docs/general/adapters.md @@ -0,0 +1,52 @@ +# Adapters + +AMS does this through two components: **serializers** and **adapters**. +Serializers describe _which_ attributes and relationships should be serialized. +Adapters describe _how_ attributes and relationships should be serialized. +You can use one of the built-in adapters (```FlattenJSON``` is the default one) or create one by your one but you won't need to implement an adapter unless you wish to use a new format or +media type with AMS. + +## Built in Adapters + +### FlattenJSON - Default + +It's the default adapter, it generates a json response without a root key. +Doesn't follow any specifc convention. + +### JSON + +It also generates a json response but always with a root key. The root key **can't be overridden**, and will be automatically defined accordingly with the objects being serialized. +Doesn't follow any specifc convention. + +### JSONAPI + +This adapter follows 1.0 of the format specified in +[jsonapi.org/format](http://jsonapi.org/format). It will include the associated +resources in the `"included"` member when the resource names are included in the +`include` option. + +```ruby + render @posts, include: ['authors', 'comments'] + # or + render @posts, include: 'authors,comments' +``` + +## Choose an Adapter + +If you want to use a different adapter, such as a JsonApi, you can change this in an initializer: + +```ruby +ActiveModel::Serializer.config.adapter = ActiveModel::Serializer::Adapter::JsonApi +``` + +or + +```ruby +ActiveModel::Serializer.config.adapter = :json_api +``` + +If you want to have a root key on your responses you should use the Json adapter, instead of the default FlattenJson: + +```ruby +ActiveModel::Serializer.config.adapter = :json +``` diff --git a/docs/general/getting_started.md b/docs/general/getting_started.md new file mode 100644 index 000000000..dda394e95 --- /dev/null +++ b/docs/general/getting_started.md @@ -0,0 +1,75 @@ +# Getting Started + +## Installation + +### ActiveModel::Serializer is already included on Rails >= 5 + +Add this line to your application's Gemfile: + +``` +gem 'active_model_serializers' +``` + +And then execute: + +``` +$ bundle +``` + +## Creating a Serializer + +The easiest way to create a new serializer is to generate a new resource, which +will generate a serializer at the same time: + +``` +$ rails g resource post title:string body:string +``` + +This will generate a serializer in `app/serializers/post_serializer.rb` for +your new model. You can also generate a serializer for an existing model with +the serializer generator: + +``` +$ rails g serializer post +``` + +The generated seralizer will contain basic `attributes` and +`has_many`/`has_one`/`belongs_to` declarations, based on the model. For example: + +```ruby +class PostSerializer < ActiveModel::Serializer + attributes :title, :body + + has_many :comments + has_one :author + + url :post +end +``` + +and + +```ruby +class CommentSerializer < ActiveModel::Serializer + attributes :name, :body + + belongs_to :post_id + + url [:post, :comment] +end +``` + +## Rails Integration + +AMS will automatically integrate with you Rails app, you won't need to update your controller, this is a example of how it will look like: + +```ruby +class PostsController < ApplicationController + + def show + @post = Post.find(params[:id]) + render json: @post + end + +end +``` diff --git a/docs/howto/add_root_key.md b/docs/howto/add_root_key.md new file mode 100644 index 000000000..37edbe82f --- /dev/null +++ b/docs/howto/add_root_key.md @@ -0,0 +1,56 @@ +# How to use add root key + +Add the root key to your API is quite simple with AMS. The **Adapter** is what determines the format of your JSON response. The default adapter is the ```FlattenJSON``` 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 correspondent root key you need to use the ```JSON``` Adapter, you can change this in an initializer: + +```ruby +ActiveModel::Serializer.config.adapter = :json_api +``` + +or + +```ruby +ActiveModel::Serializer.config.adapter = ActiveModel::Serializer::Adapter::Json +``` + +This 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" + } + ] +} +```