class ContactResource < JSONAPI::Resource end

class BaseResource < JSONAPI::Resource abstract has_one :creator end class ContactResource < BaseResource end

class VehicleResource < JSONAPI::Resource immutable has_one :owner attributes :make, :model, :serial_number end class CarResource < VehicleResource attributes :drive_layout has_one :driver end class BoatResource < VehicleResource attributes :length_at_water_line has_one :captain end # routes jsonapi_resources :vehicles jsonapi_resources :cars jsonapi_resources :boats

class ApplicationController < JSONAPI::ResourceController def context {current_user: current_user} end end # Specific resource controllers derive from ApplicationController # and share its context class PeopleController < ApplicationController end # Assuming you don't permit user_id (so the client won't assign a wrong user to own the object) # you can ensure the current user is assigned the record by using the controller's context hash. class PeopleResource < JSONAPI::Resource before_save do @model.user_id = context[:current_user].id if @model.new_record? end end

class ContactResource < JSONAPI::Resource attribute :name_first attributes :name_last, :email, :twitter end

class ContactResource < JSONAPI::Resource attributes :name_first, :name_last, :email, :twitter attribute :full_name def full_name "#{@model.name_first}, #{@model.name_last}" end end

class ContactResource < JSONAPI::Resource attribute :name_first, delegate: :first_name attribute :name_last, delegate: :last_name end

class AuthorResource < JSONAPI::Resource attributes :name, :email model_name 'Person' has_many :posts def fetchable_fields if (context[:current_user].guest) super - [:email] else super end end end

class ContactResource < JSONAPI::Resource attributes :name_first, :name_last, :full_name def full_name "#{@model.name_first}, #{@model.name_last}" end def self.updatable_fields(context) super - [:full_name] end def self.creatable_fields(context) super - [:full_name] end end

class PostResource < JSONAPI::Resource attributes :title, :body def self.sortable_fields(context) super(context) - [:body] end end

class Book < ActiveRecord::Base belongs_to :author end class Author < ActiveRecord::Base has_many :books end class BookResource < JSONAPI::Resource attributes :title, :body def self.sortable_fields(context) super(context) << :"author.name" end end

 def self.default_sort [{field: 'name_last', direction: :desc}, {field: 'name_first', direction: :desc}] end

class PersonResource < JSONAPI::Resource attributes :name, :email attribute :last_login_time, format: :date_with_timezone end

# Given Models class Person < ActiveRecord::Base has_many :spoken_languages validates :name, :email, :spoken_languages, presence: true end class SpokenLanguage < ActiveRecord::Base belongs_to :person, inverse_of: :spoken_languages validates :person, :language_code, presence: true end # Resource with getters and setter class PersonResource < JSONAPI::Resource attributes :name, :email, :spoken_languages # Getter def spoken_languages @model.spoken_languages.pluck(:language_code) end # Setter (because spoken_languages needed for creation) def spoken_languages=(new_spoken_language_codes) @model.spoken_languages.destroy_all new_spoken_language_codes.each do |new_lang_code| @model.spoken_languages.build(language_code: new_lang_code) end end end

JSONAPI.configure do |config| # Allowed values are :integer(default), :uuid, :string, or a proc config.resource_key_type = :uuid end

class ContactResource < JSONAPI::Resource attribute :id attributes :name_first, :name_last, :email, :twitter key_type :uuid end

JSONAPI.configure do |config| config.resource_key_type = -> (key, context) { key && String(key) } end

class AuthorResource < JSONAPI::Resource attribute :name model_name 'Person' has_many :posts end

class AuthorResource < JSONAPI::Resource attribute :name model_name 'Person' model_hint model: Commenter, resource: :special_person has_many :posts has_many :commenters end

class AuthorResource < JSONAPI::Resource model_name 'Legacy::Person', add_model_hint: false end

class PostResource < JSONAPI::Resource attributes :title, :body relationship :author, to: :one end

class AuthorResource < JSONAPI::Resource attribute :name relationship :posts, to: :many end

class PostResource < JSONAPI::Resource attributes :title, :body has_one :author end

class AuthorResource < JSONAPI::Resource attribute :name has_many :posts end

class CommentResource < JSONAPI::Resource attributes :body has_one :post has_one :author, class_name: 'Person' has_many :tags, acts_as_set: true end class ExpenseEntryResource < JSONAPI::Resource attributes :cost, :transaction_date has_one :currency, class_name: 'Currency', foreign_key: 'currency_code' has_one :employee end class TagResource < JSONAPI::Resource attributes :name has_one :taggable, polymorphic: true end

class BookResource < JSONAPI::Resource # Only book_admins may see unapproved comments for a book. Using # a lambda to select the correct relation on the model has_many :book_comments, relation_name: -> (options = {}) { context = options[:context] current_user = context ? context[:current_user] : nil unless current_user && current_user.book_admin :approved_book_comments else :book_comments end } ... end

class TaggableResource < JSONAPI::Resource; end class TaggablesController < JSONAPI::ResourceController; end

class ContactResource < JSONAPI::Resource attributes :name_first, :name_last, :email, :twitter filter :id filters :name_first, :name_last end

 class CommentResource < JSONAPI::Resource attributes :body, :status has_one :post has_one :author filter :status, default: 'published,pending' end

# When given the following parameter:'filter[visibility]': 'public' filter :visibility, apply: ->(records, value, _options) { records.where('users.publicly_visible = ?', value[0] == 'public') }

def self.apply_filter(records, filter, value, options) case filter when :last_name, :first_name, :name if value.is_a?(Array) value.each do |val| records = records.where(_model_class.arel_table[filter].matches(val)) end records else records.where(_model_class.arel_table[filter].matches(value)) end else super(records, filter, value) end end

 filter :ids, verify: ->(values, context) { verify_keys(values, context) values }, apply: ->(records, value, _options) { records.where('id IN (?)', value) }

# A more complex example, showing how to filter for any overlap between the # value array and the possible_ids, using both verify and apply callables. filter :possible_ids, verify: ->(values, context) { values.map {|value| value.to_i} }, apply: ->(records, value, _options) { records.where('possible_ids && ARRAY[?]', value) }

class PostResource < JSONAPI::Resource attributes :title, :body def self.records(options = {}) context = options[:context] context[:current_user].posts end end

class PostResource < JSONAPI::Resource has_one :author has_many :comments # def record_for_author # relationship = self.class._relationship(:author) # relation_name = relationship.relation_name(context: @context) # records_for(relation_name) # end # def records_for_comments # relationship = self.class._relationship(:comments) # relation_name = relationship.relation_name(context: @context) # records_for(relation_name) # end end

class BaseResource < JSONAPI::Resource def records_for(relation_name) context = options[:context] records = _model.public_send(relation_name) unless context[:current_user].can_view?(records) raise NotAuthorizedError end records end end

# config/initializer/jsonapi-resources.rb JSONAPI.configure do |config| config.exception_class_whitelist = [NotAuthorizedError] end

class ApiController < ApplicationController rescue_from NotAuthorizedError, with: :reject_forbidden_request def reject_forbidden_request render json: {error: 'Forbidden'}, :status => 403 end end

def self.apply_filter(records, filter, value, options) case filter when :visibility records.where('users.publicly_visible = ?', value == :public) when :last_name, :first_name, :name if value.is_a?(Array) value.each do |val| records = records.where(_model_class.arel_table[filter].matches(val)) end records else records.where(_model_class.arel_table[filter].matches(value)) end else super(records, filter, value) end end

def self.apply_sort(records, order_options, context = {}) if order_options.has?(:trending) records = records.order_by_trending_scope order_options - [:trending] end super(records, order_options, context) end

class AuthorResource < JSONAPI::Resource attribute :name model_name 'Person' has_many :posts filter :name def self.find(filters, options = {}) context = options[:context] authors = context[:current_user].find_authors(filters) return authors.map do |author| self.new(author, context) end end end

class SingleRecordPaginator < JSONAPI::Paginator def initialize(params) # param parsing and validation here @page = params.to_i end def apply(relation, order_options) relation.offset(@page).limit(1) end end

JSONAPI.configure do |config| # built in paginators are :none, :offset, :paged config.default_paginator = :offset config.default_page_size = 10 config.maximum_page_size = 20 end

class BookResource < JSONAPI::Resource attribute :title attribute :isbn paginator :offset end

class BookResource < JSONAPI::Resource attribute :title attribute :isbn def meta(options) { copyright: 'API Copyright 2015 - XYZ Corp.', computed_copyright: options[:serialization_options][:copyright], last_updated_at: _model.updated_at } end end

class CityCouncilMeeting < JSONAPI::Resource attribute :title, :location, :approved def custom_links(options) { minutes: options[:serializer].link_builder.self_link(self) + "/minutes" } end end

class CityCouncilMeeting < JSONAPI::Resource attribute :title, :location, :approved delegate :approved?, to: :model def custom_links(options) extra_links = {} if approved? extra_links[:minutes] = options[:serializer].link_builder.self_link(self) + "/minutes" end extra_links end end ``` It's also possibly to suppress the default `self` link by returning a hash with `{self: nil}`:  ````ruby class Selfless < JSONAPI::Resource  def custom_links(options)  {self: nil}  end end ```  #### Callbacks  `ActiveSupport::Callbacks` is used to provide callback functionality, so the behavior is very similar to what you may be used to from `ActiveRecord`.  For example, you might use a callback to perform authorization on your resource before an action.  ```ruby class BaseResource < JSONAPI::Resource  before_create :authorize_create   def authorize_create  # ...  end end ```  The types of supported callbacks are: - `before` - `after` - `around`  ##### `JSONAPI::Resource` Callbacks  Callbacks can be defined for the following `JSONAPI::Resource` events:  - `:create` - `:update` - `:remove` - `:save` - `:create_to_many_link` - `:replace_to_many_links` - `:create_to_one_link` - `:replace_to_one_link` - `:remove_to_many_link` - `:remove_to_one_link` - `:replace_fields`  ###### Relationship Reflection  By default updates to relationships only invoke callbacks on the primary Resource. By setting the `use_relationship_reflection` [Configuration] (#configuration) option updates to `has_many` relationships will occur on the related resource, triggering callbacks on both resources.  ##### `JSONAPI::Processor` Callbacks  Callbacks can also be defined for `JSONAPI::Processor` events: - `:operation`: Any individual operation. - `:find`: A `find` operation is being processed. - `:show`: A `show` operation is being processed. - `:show_relationship`: A `show_relationship` operation is being processed. - `:show_related_resource`: A `show_related_resource` operation is being processed. - `:show_related_resources`: A `show_related_resources` operation is being processed. - `:create_resource`: A `create_resource` operation is being processed. - `:remove_resource`: A `remove_resource` operation is being processed. - `:replace_fields`: A `replace_fields` operation is being processed. - `:replace_to_one_relationship`: A `replace_to_one_relationship` operation is being processed. - `:create_to_many_relationship`: A `create_to_many_relationship` operation is being processed. - `:replace_to_many_relationship`: A `replace_to_many_relationship` operation is being processed. - `:remove_to_many_relationship`: A `remove_to_many_relationship` operation is being processed. - `:remove_to_one_relationship`: A `remove_to_one_relationship` operation is being processed.  See [Operation Processors] (#operation-processors) for details on using OperationProcessors  ##### `JSONAPI::OperationsProcessor` Callbacks (a removed feature)  Note: The `JSONAPI::OperationsProcessor` has been removed and replaced with the `JSONAPI::OperationDispatcher` and `Processor` classes per resource. The callbacks have been renamed and moved to the `Processor`s, with the exception of the `operations` callback which is now on the controller.  ### Controllers  There are two ways to implement a controller for your resources. Either derive from `ResourceController` or import the `ActsAsResourceController` module.  ##### ResourceController  `JSONAPI::Resources` provides a class, `ResourceController`, that can be used as the base class for your controllers. `ResourceController` supports `index`, `show`, `create`, `update`, and `destroy` methods. Just deriving your controller from `ResourceController` will give you a fully functional controller.  For example:  ```ruby class PeopleController < JSONAPI::ResourceController  end ```  Of course you are free to extend this as needed and override action handlers or other methods.  A jsonapi-controller generator is avaliable  ``` rails generate jsonapi:controller contact ```  ###### ResourceControllerMetal  `JSONAPI::Resources` also provides an alternative class to `ResourceController` called `ResourceControllerMetal`. In order to provide a lighter weight controller option this strips the controller down to just the classes needed to work with `JSONAPI::Resources`.  For example:  ```ruby class PeopleController < JSONAPI::ResourceControllerMetal  end ```  Note: This may not provide all of the expected controller capabilities if you are using additional gems such as DoorKeeper.  ###### Serialization Options  Additional options can be passed to the serializer using the `serialization_options` method.  For example:  ```ruby class ApplicationController < JSONAPI::ResourceController  def serialization_options  {copyright: 'Copyright 2015'}  end end ```  These `serialization_options` are passed to the `meta` method used to generate resource `meta` values.  ##### ActsAsResourceController  `JSONAPI::Resources` also provides a module, `JSONAPI::ActsAsResourceController`. You can include this module to mix in all the features of `ResourceController` into your existing controller class.  For example:  ```ruby class PostsController < ActionController::Base  include JSONAPI::ActsAsResourceController end ```  #### Namespaces  JSONAPI::Resources supports namespacing of controllers and resources. With namespacing you can version your API.  If you namespace your controller it will require a namespaced resource.  In the following example we have a `resource` that isn't namespaced, and one that has now been namespaced. There are slight differences between the two resources, as might be seen in a new version of an API: ```ruby class PostResource < JSONAPI::Resource attribute :title attribute :body attribute :subject has_one :author, class_name: 'Person' has_one :section has_many :tags, acts_as_set: true has_many :comments, acts_as_set: false def subject @model.title end filters :title, :author, :tags, :comments filter :id end ... module Api module V1 class PostResource < JSONAPI::Resource # V1 replaces the non-namespaced resource # V1 no longer supports tags and now calls author 'writer' attribute :title attribute :body attribute :subject has_one :writer, foreign_key: 'author_id' has_one :section has_many :comments, acts_as_set: false def subject @model.title end filters :writer end class WriterResource < JSONAPI::Resource attributes :name, :email model_name 'Person' has_many :posts filter :name end end end ``` The following controllers are used: ```ruby class PostsController < JSONAPI::ResourceController end  module Api  module V1  class PostsController < JSONAPI::ResourceController  end  end end ``` You will also need to namespace your routes: ```ruby Rails.application.routes.draw do   jsonapi_resources :posts   namespace :api do  namespace :v1 do  jsonapi_resources :posts  end  end end ``` When a namespaced `resource` is used, any related `resources` must also be in the same namespace. #### Error codes Error codes are provided for each error object returned, based on the error. These errors are: ```ruby module JSONAPI  VALIDATION_ERROR = '100'  INVALID_RESOURCE = '101'  FILTER_NOT_ALLOWED = '102'  INVALID_FIELD_VALUE = '103'  INVALID_FIELD = '104'  PARAM_NOT_ALLOWED = '105'  PARAM_MISSING = '106'  INVALID_FILTER_VALUE = '107'  COUNT_MISMATCH = '108'  KEY_ORDER_MISMATCH = '109'  KEY_NOT_INCLUDED_IN_URL = '110'  INVALID_INCLUDE = '112'  RELATION_EXISTS = '113'  INVALID_SORT_CRITERIA = '114'  INVALID_LINKS_OBJECT = '115'  TYPE_MISMATCH = '116'  INVALID_PAGE_OBJECT = '117'  INVALID_PAGE_VALUE = '118'  INVALID_FIELD_FORMAT = '119'  INVALID_FILTERS_SYNTAX = '120'  SAVE_FAILED = '121'  FORBIDDEN = '403'  RECORD_NOT_FOUND = '404'  NOT_ACCEPTABLE = '406'  UNSUPPORTED_MEDIA_TYPE = '415'  LOCKED = '423' end ``` These codes can be customized in your app by creating an initializer to override any or all of the codes. In addition textual error codes can be returned by setting the configuration option `use_text_errors = true`. For example: ```ruby JSONAPI.configure do |config|  config.use_text_errors = true end ``` #### Handling Exceptions By default, all exceptions raised downstream from a resource controller will be caught, logged, and a ```500 Internal Server Error``` will be rendered. Exceptions can be whitelisted in the config to pass through the handler and be caught manually, or you can pass a callback from a resource controller to insert logic into the rescue block without interrupting the control flow. This can be particularly useful for additional logging or monitoring without the added work of rendering responses. Pass a block, refer to controller class methods, or both. Note that methods must be defined as class methods on a controller and accept one parameter, which is passed the exception object that was rescued. ```ruby class ApplicationController < JSONAPI::ResourceController on_server_error :first_callback #or # on_server_error do |error| #do things #end def self.first_callback(error) #env["airbrake.error_id"] = notify_airbrake(error) end end ```  #### Action Callbacks  ##### verify_content_type_header  By default, when controllers extend functionalities from `jsonapi-resources`, the `ActsAsResourceController#verify_content_type_header` method will be triggered before `create`, `update`, `create_relationship` and `update_relationship` actions. This method is responsible for checking if client's request corresponds to the correct media type required by [JSON API](http://jsonapi.org/format/#content-negotiation-clients): `application/vnd.api+json`.  In case you need to check the media type for custom actions, just make sure to call the method in your controller's `before_action`: ```ruby class UsersController < JSONAPI::ResourceController  before_action :verify_content_type_header, only: [:auth]   def auth  # some crazy auth code goes here  end end ``` ### Operation Processors Operation Processors are called to perform the operation(s) that make up a request. The controller (through the `OperationDispatcher`), creates an `OperatorProcessor` to handle each operation. The processor is created based on the resource name, including the namespace. If a processor does not exist for a resource (namespace matters) the default operation processor is used instead. The default processor can be changed by a configuration setting. Defining a custom `Processor` allows for custom callback handling of each operation type for each resource type. For example: ```ruby class Api::V4::BookProcessor < JSONAPI::Processor  after_find do  unless @result.is_a?(JSONAPI::ErrorsOperationResult)  @result.meta[:total_records_found] = @result.record_count  end  end end ``` This simple example uses a callback to update the result's meta property with the total count of records (a redundant feature only for example purposes), if there wasn't an error in the operation. It is also possible to override the `find` method as well if a different behavior is needed, for example: ```ruby class Api::V4::BookProcessor < JSONAPI::Processor  def find  filters = params[:filters]  include_directives = params[:include_directives]  sort_criteria = params.fetch(:sort_criteria, [])  paginator = params[:paginator]   verified_filters = resource_klass.verify_filters(filters, context)  resource_records = resource_klass.find(verified_filters,  context: context,  include_directives: include_directives,  sort_criteria: sort_criteria,  paginator: paginator)   page_options = {}  # Overriding the default record count logic to always include it in the meta  #if (JSONAPI.configuration.top_level_meta_include_record_count ||  # (paginator && paginator.class.requires_record_count))  page_options[:record_count] = resource_klass.find_count(verified_filters,  context: context,  include_directives: include_directives)  #end end ``` Note: The authors of this gem expect the most common uses cases to be handled using the callbacks. It is likely that the internal functionality of the operation processing methods will change, at least for several revisions. Effort will be made to call this out in release notes. You have been warned. ### Serializer The `ResourceSerializer` can be used to serialize a resource into JSON API compliant JSON. `ResourceSerializer` must be  initialized with the primary resource type it will be serializing. `ResourceSerializer` has a `serialize_to_hash`  method that takes a resource instance or array of resource instances to serialize. For example:  ```ruby post = Post.find(1) JSONAPI::ResourceSerializer.new(PostResource).serialize_to_hash(PostResource.new(post, nil)) ```  Note: If your resource needs to access to state from a context hash, make sure to pass the context hash as the second argument of the resource class new method. For example:  ```ruby post = Post.find(1) context = { current_user: current_user } JSONAPI::ResourceSerializer.new(PostResource).serialize_to_hash(PostResource.new(post, context)) ``` This returns results like this: ```json {  "data": {  "type": "posts",  "id": "1",  "links": {  "self": "http://example.com/posts/1"  },  "attributes": {  "title": "New post",  "body": "A body!!!",  "subject": "New post"  },  "relationships": {  "section": {  "links": {  "self": "http://example.com/posts/1/relationships/section",  "related": "http://example.com/posts/1/section"  },  "data": null  },  "author": {  "links": {  "self": "http://example.com/posts/1/relationships/author",  "related": "http://example.com/posts/1/author"  },  "data": {  "type": "people",  "id": "1"  }  },  "tags": {  "links": {  "self": "http://example.com/posts/1/relationships/tags",  "related": "http://example.com/posts/1/tags"  }  },  "comments": {  "links": {  "self": "http://example.com/posts/1/relationships/comments",  "related": "http://example.com/posts/1/comments"  }  }  }  } } ``` #### Serializer options The `ResourceSerializer` can be initialized with some optional parameters: ##### `include` An array of resources. Nested resources can be specified with dot notation. *Purpose*: determines which objects will be side loaded with the source objects in an `included` section *Example*: ```include: ['comments','author','comments.tags','author.posts']``` ##### `fields` A hash of resource types and arrays of fields for each resource type. *Purpose*: determines which fields are serialized for a resource type. This encompasses both attributes and relationship ids in the links section for a resource. Fields are global for a resource type. *Example*: ```fields: { people: [:email, :comments], posts: [:title, :author], comments: [:body, :post]}``` ```ruby post = Post.find(1) include_resources = ['comments','author','comments.tags','author.posts']  JSONAPI::ResourceSerializer.new(PostResource, include: include_resources,  fields: {  people: [:email, :comments],  posts: [:title, :author],  tags: [:name],  comments: [:body, :post]  } ).serialize_to_hash(PostResource.new(post, nil)) ``` #### Formatting JR by default uses some simple rules to format (and unformat) an attribute for (de-)serialization. Strings and Integers are output to JSON as is, and all other values have `.to_s` applied to them. This outputs something in all cases, but it is certainly not correct for every situation. If you want to change the way an attribute is (de-)serialized you have a couple of ways. The simplest method is to create a getter (and setter) method on the resource which overrides the attribute and apply the (un-)formatting there. For example: ```ruby class PersonResource < JSONAPI::Resource  attributes :name, :email, :last_login_time   # Setter example  def email=(new_email)  @model.email = new_email.downcase  end   # Getter example  def last_login_time  @model.last_login_time.in_time_zone(@context[:current_user].time_zone).to_s  end end ``` This is simple to implement for a one off situation, but not for example if you want to apply the same formatting rules to all DateTime fields in your system. Another issue is the attribute on the resource will always return a formatted response, whether you want it or not. ##### Value Formatters To overcome the above limitations JR uses Value Formatters. Value Formatters allow you to control the way values are handled for an attribute. The `format` can be set per attribute as it is declared in the resource. For example: ```ruby class PersonResource < JSONAPI::Resource  attributes :name, :email, :spoken_languages  attribute :last_login_time, format: :date_with_utc_timezone   # Getter/Setter for spoken_languages ... end ``` A Value formatter has a `format` and an `unformat` method. Here's the base ValueFormatter and DefaultValueFormatter for reference:  ```ruby module JSONAPI  class ValueFormatter < Formatter  class << self  def format(raw_value)  super(raw_value)  end   def unformat(value)  super(value)  end  ...  end  end end  class DefaultValueFormatter < JSONAPI::ValueFormatter  class << self  def format(raw_value)  case raw_value  when Date, Time, DateTime, ActiveSupport::TimeWithZone, BigDecimal  # Use the as_json methods added to various base classes by ActiveSupport  return raw_value.as_json  else  return raw_value  end  end  end end ```  You can also create your own Value Formatter. Value Formatters must be named with the `format` name followed by `ValueFormatter`, i.e. `DateWithUTCTimezoneValueFormatter` and derive from `JSONAPI::ValueFormatter`. It is recommended that you create a directory for your formatters, called `formatters`.  The `format` method is called by the `ResourceSerializer` as is serializing a resource. The format method takes the `raw_value` parameter. `raw_value` is the value as read from the model.  The `unformat` method is called when processing the request. Each incoming attribute (except `links`) are run through the `unformat` method. The `unformat` method takes a `value`, which is the value as it comes in on the request. This allows you process the incoming value to alter its state before it is stored in the model.  ###### Use a Different Default Value Formatter  Another way to handle formatting is to set a different default value formatter. This will affect all attributes that do not have a `format` set. You can do this by overriding the `default_attribute_options` method for a resource (or a base resource for a system wide change).  ```ruby  def self.default_attribute_options  {format: :my_default}  end ```  and  ```ruby class MyDefaultValueFormatter < DefaultValueFormatter  class << self  def format(raw_value)  case raw_value  when DateTime  return super(raw_value.in_time_zone('UTC'))  else  return super  end  end  end end ```  This way all DateTime values will be formatted to display in the UTC timezone.  #### Key Format  By default JR uses dasherized keys as per the [JSON API naming recommendations](http://jsonapi.org/recommendations/#naming). This can be changed by specifying a different key formatter.  For example, to use camel cased keys with an initial lowercase character (JSON's default) create an initializer and add the following: ```ruby JSONAPI.configure do |config|  # built in key format options are :underscored_key, :camelized_key and :dasherized_key  config.json_key_format = :camelized_key end ``` This will cause the serializer to use the `CamelizedKeyFormatter`. You can also create your own `KeyFormatter`, for example: ```ruby class UpperCamelizedKeyFormatter < JSONAPI::KeyFormatter  class << self  def format(key)  super.camelize(:upper)  end  end end ``` You would specify this in `JSONAPI.configure` as `:upper_camelized`. ### Routing JR has a couple of helper methods available to assist you with setting up routes. ##### `jsonapi_resources` Like `resources` in `ActionDispatch`, `jsonapi_resources` provides resourceful routes mapping between HTTP verbs and URLs and controller actions. This will also setup mappings for relationship URLs for a resource's relationships. For example:  ```ruby Rails.application.routes.draw do  jsonapi_resources :contacts  jsonapi_resources :phone_numbers end ```  gives the following routes  ```  Prefix Verb URI Pattern Controller#Action contact_relationships_phone_numbers GET /contacts/:contact_id/relationships/phone-numbers(.:format) contacts#show_relationship {:relationship=>"phone_numbers"}  POST /contacts/:contact_id/relationships/phone-numbers(.:format) contacts#create_relationship {:relationship=>"phone_numbers"}  DELETE /contacts/:contact_id/relationships/phone-numbers/:keys(.:format) contacts#destroy_relationship {:relationship=>"phone_numbers"}  contact_phone_numbers GET /contacts/:contact_id/phone-numbers(.:format) phone_numbers#get_related_resources {:relationship=>"phone_numbers", :source=>"contacts"}  contacts GET /contacts(.:format) contacts#index  POST /contacts(.:format) contacts#create  contact GET /contacts/:id(.:format) contacts#show  PATCH /contacts/:id(.:format) contacts#update  PUT /contacts/:id(.:format) contacts#update  DELETE /contacts/:id(.:format) contacts#destroy  phone_number_relationships_contact GET /phone-numbers/:phone_number_id/relationships/contact(.:format) phone_numbers#show_relationship {:relationship=>"contact"}  PUT|PATCH /phone-numbers/:phone_number_id/relationships/contact(.:format) phone_numbers#update_relationship {:relationship=>"contact"}  DELETE /phone-numbers/:phone_number_id/relationships/contact(.:format) phone_numbers#destroy_relationship {:relationship=>"contact"}  phone_number_contact GET /phone-numbers/:phone_number_id/contact(.:format) contacts#get_related_resource {:relationship=>"contact", :source=>"phone_numbers"}  phone_numbers GET /phone-numbers(.:format) phone_numbers#index  POST /phone-numbers(.:format) phone_numbers#create  phone_number GET /phone-numbers/:id(.:format) phone_numbers#show  PATCH /phone-numbers/:id(.:format) phone_numbers#update  PUT /phone-numbers/:id(.:format) phone_numbers#update  DELETE /phone-numbers/:id(.:format) phone_numbers#destroy ```  ##### `jsonapi_resource`  Like `jsonapi_resources`, but for resources you lookup without an id.  #### Nested Routes  By default nested routes are created for getting related resources and manipulating relationships. You can control the nested routes by passing a block into `jsonapi_resources` or `jsonapi_resource`. An empty block will not create any nested routes. For example:  ```ruby Rails.application.routes.draw do  jsonapi_resources :contacts do  end end ```  gives routes that are only related to the primary resource, and none for its relationships:  ```  Prefix Verb URI Pattern Controller#Action  contacts GET /contacts(.:format) contacts#index  POST /contacts(.:format) contacts#create  contact GET /contacts/:id(.:format) contacts#show  PATCH /contacts/:id(.:format) contacts#update  PUT /contacts/:id(.:format) contacts#update  DELETE /contacts/:id(.:format) contacts#destroy ```  To manually add in the nested routes you can use the `jsonapi_links`, `jsonapi_related_resources` and `jsonapi_related_resource` inside the block. Or, you can add the default set of nested routes using the `jsonapi_relationships` method. For example:  ```ruby Rails.application.routes.draw do  jsonapi_resources :contacts do  jsonapi_relationships  end end ```  ###### `jsonapi_links`  You can add relationship routes in with `jsonapi_links`, for example:  ```ruby Rails.application.routes.draw do  jsonapi_resources :contacts do  jsonapi_links :phone_numbers  end end ```  Gives the following routes:  ``` contact_relationships_phone_numbers GET /contacts/:contact_id/relationships/phone-numbers(.:format) contacts#show_relationship {:relationship=>"phone_numbers"}  POST /contacts/:contact_id/relationships/phone-numbers(.:format) contacts#create_relationship {:relationship=>"phone_numbers"}  DELETE /contacts/:contact_id/relationships/phone-numbers/:keys(.:format) contacts#destroy_relationship {:relationship=>"phone_numbers"}  contacts GET /contacts(.:format) contacts#index  POST /contacts(.:format) contacts#create  contact GET /contacts/:id(.:format) contacts#show  PATCH /contacts/:id(.:format) contacts#update  PUT /contacts/:id(.:format) contacts#update  DELETE /contacts/:id(.:format) contacts#destroy  ```  The new routes allow you to show, create and destroy the relationships between resources.  ###### `jsonapi_related_resources`  Creates a nested route to GET the related has_many resources. For example:  ```ruby Rails.application.routes.draw do  jsonapi_resources :contacts do  jsonapi_related_resources :phone_numbers  end end  ```  gives the following routes:  ```  Prefix Verb URI Pattern Controller#Action contact_phone_numbers GET /contacts/:contact_id/phone-numbers(.:format) phone_numbers#get_related_resources {:relationship=>"phone_numbers", :source=>"contacts"}  contacts GET /contacts(.:format) contacts#index  POST /contacts(.:format) contacts#create  contact GET /contacts/:id(.:format) contacts#show  PATCH /contacts/:id(.:format) contacts#update  PUT /contacts/:id(.:format) contacts#update  DELETE /contacts/:id(.:format) contacts#destroy  ```  A single additional route was created to allow you GET the phone numbers through the contact.  ###### `jsonapi_related_resource`  Like `jsonapi_related_resources`, but for has_one related resources.  ```ruby Rails.application.routes.draw do  jsonapi_resources :phone_numbers do  jsonapi_related_resource :contact  end end ```  gives the following routes:  ```  Prefix Verb URI Pattern Controller#Action phone_number_contact GET /phone-numbers/:phone_number_id/contact(.:format) contacts#get_related_resource {:relationship=>"contact", :source=>"phone_numbers"}  phone_numbers GET /phone-numbers(.:format) phone_numbers#index  POST /phone-numbers(.:format) phone_numbers#create  phone_number GET /phone-numbers/:id(.:format) phone_numbers#show  PATCH /phone-numbers/:id(.:format) phone_numbers#update  PUT /phone-numbers/:id(.:format) phone_numbers#update  DELETE /phone-numbers/:id(.:format) phone_numbers#destroy  ```  ### Authorization  Currently `json-api-resources` doesn't come with built-in primitives for authorization. However multiple users of the framework have come up with different approaches, check out: - [jsonapi-authorization](https://github.com/venuu/jsonapi-authorization) - [pundit-resources](https://github.com/togglepro/pundit-resources) Refer to the comments/discussion [here](https://github.com/cerebris/jsonapi-resources/issues/16#issuecomment-222438975) for the differences between approaches ### Resource Caching To improve the response time of GET requests, JR can cache the generated JSON fragments for Resources which are suitable. First, set `config.resource_cache` to an ActiveSupport cache store: ```ruby JSONAPI.configure do |config|  config.resource_cache = Rails.cache end ``` Then, on each Resource you want to cache, call the `caching` method: ```ruby class PostResource < JSONAPI::Resource  caching end ``` See the caveats section below for situations where you might not want to enable caching on particular Resources. The Resource model must also have a field that is updated whenever any of the model's data changes. The default Rails timestamps handle this pretty well, and the default cache key field is `updated_at` for this reason. You can use an alternate field (which you are then responsible for updating) by calling the `cache_field` method:  ```ruby class PostResource < JSONAPI::Resource  caching  cache_field :change_counter   before_save do  if self.change_counter.nil?  self.change_counter = 1  elsif self.changed?  self.change_counter += 1  end  end   after_touch do  update_attribute(:change_counter, self.change_counter + 1)  end end ```  If context affects the content of the serialized result, you must define a class method `attribute_caching_context` on that Resource, which should return a different value for contexts that produce different results. In particular, if the `meta` or `fetchable_fields` methods, or any method providing the actual content of an attribute, changes depending on context, then you must provide `attribute_caching_context`. The actual value it returns isn't important, what matters is that the value must be different if any relevant part of the context is different. ```ruby class PostResource < JSONAPI::Resource caching attributes :title, :body, :secret_field def fetchable_fields return super if context.user.superuser? return super - [:secret_field] end def meta if context.user.can_see_creation_dates? return { created: _model.created_at } else return {} end end def self.attribute_caching_context(context) return { admin: context.user.superuser?, creation_date_viewer: context.user.can_see_creation_dates? } end end ```  #### Caching Caveats  * Models for cached Resources must update a cache key field whenever their data changes. However, if you bypass Rails and e.g. alter the database row directly without changing the `updated_at` field, the cached entry for that resource will be inaccurate. Also, `updated_at` provides a narrow race condition window; if a resource is updated twice in the same second, it's possible that only the first update will be cached. If you're concerned about this, you will need to find a way to make sure your models' cache fields change on every update, e.g. by using a unique random value or a monotonic clock. * If an attribute's value is affected by related resources, e.g. the `spoken_languages` example above, then changes to the related resource must also touch the cache field on the resource that uses it. The `belongs_to` relation in ActiveRecord provides a `:touch` option for this purpose. * JR does not actively clean the cache, so you must use an ActiveSupport cache that automatically expires old entries, or you will leak resources. The MemoryCache built in to Rails does this by default, but other caches will have to be configured with an `:expires_in` option and/or a cache-specific clearing mechanism. * Similarly, if you make a substantial code change that affects a lot of serialized representations (i.e. changing the way an attribute is shown), you'll have to clear out all relevant cache entries yourself. The simplest way to do this is to run `JSONAPI.configuration.resource_cache.clear` from the console. You do not have to do this after merely adding or removing attributes; only changes that affect the actual content of attributes require manual cache clearing. * If resource caching is enabled at all, then custom relationship methods on any resource might not always be used, even resources that are not cached. For example, if you manually define a `comments` method or `records_for_comments` method on a Resource that `has_many :comments`, you cannot expect it to be used when caching is enabled, even if you never call `caching` on that particular Resource. Instead, you should use relationship name lambdas. * The above also applies to custom `find` or `find_by_key` methods. Instead, if you are using resource caching anywhere in your app, try overriding the `find_records` method to return an appropriate `ActiveRecord::Relation`. * Caching relies on ActiveRecord features; you cannot enable caching on resources based on non-AR models, e.g. PORO objects or singleton resources. * If you write a custom `ResourceSerializer` which takes new options, then you must define `config_description` to include those options if they might impact the serialized value:  ```ruby class MySerializer < JSONAPI::ResourceSerializer def initialize(primary_resource_klass, options = {}) @my_special_option = options.delete(:my_special_option) super end def config_description(resource_klass) super.merge({my_special_option: @my_special_option}) end end ```  ## Configuration  JR has a few configuration options. Some have already been mentioned above. To set configuration options create an initializer and add the options you wish to set. All options have defaults, so you only need to set the options that are different. The default options are shown below.  If using custom classes (such as a CustomPaginator), be sure to require them at the top of the initializer before usage.  ```ruby JSONAPI.configure do |config| #:underscored_key, :camelized_key, :dasherized_key, or custom config.json_key_format = :dasherized_key #:underscored_route, :camelized_route, :dasherized_route, or custom config.route_format = :dasherized_route # Default Processor, used if a resource specific one is not defined. # Must be a class config.default_processor_klass = JSONAPI::Processor #:integer, :uuid, :string, or custom (provide a proc) config.resource_key_type = :integer # optional request features config.allow_include = true config.allow_sort = true config.allow_filter = true # How to handle unsupported attributes and relationships which are provided in the request # true => raises an error # false => allows the request to continue. A warning is included in the response meta data indicating # the fields which were ignored. This is useful for client libraries which send extra parameters. config.raise_if_parameters_not_allowed = true # :none, :offset, :paged, or a custom paginator name config.default_paginator = :none # Output pagination links at top level config.top_level_links_include_pagination = true config.default_page_size = 10 config.maximum_page_size = 20 # Output the record count in top level meta data for find operations config.top_level_meta_include_record_count = false config.top_level_meta_record_count_key = :record_count # For :paged paginators, the following are also available config.top_level_meta_include_page_count = false config.top_level_meta_page_count_key = :page_count config.use_text_errors = false # List of classes that should not be rescued by the operations processor. # For example, if you use Pundit for authorization, you might # raise a Pundit::NotAuthorizedError at some point during operations # processing. If you want to use Rails' `rescue_from` macro to # catch this error and render a 403 status code, you should add # the `Pundit::NotAuthorizedError` to the `exception_class_whitelist`. # Subclasses of the whitelisted classes will also be whitelisted. config.exception_class_whitelist = [] # Resource Linkage # Controls the serialization of resource linkage for non compound documents # NOTE: always_include_to_many_linkage_data is not currently implemented config.always_include_to_one_linkage_data = false # Relationship reflection invokes the related resource when updates # are made to a has_many relationship. By default relationship_reflection # is turned off because it imposes a small performance penalty. config.use_relationship_reflection = false # Allows transactions for creating and updating records # Set this to false if your backend does not support transactions (e.g. Mongodb) config.allow_transactions = true # Formatter Caching # Set to false to disable caching of string operations on keys and links. # Note that unlike the resource cache, formatter caching is always done # internally in-memory and per-thread; no ActiveSupport::Cache is used. config.cache_formatters = true # Resource cache # An ActiveSupport::Cache::Store or similar, used by Resources with caching enabled. # Set to `nil` (the default) to disable caching, or to `Rails.cache` to use the # Rails cache store. config.resource_cache = nil # Default resource cache field # On Resources with caching enabled, this field will be used to check for out-of-date # cache entries, unless overridden on a specific Resource. Defaults to "updated_at". config.default_resource_cache_field = :updated_at # Resource cache digest function # Provide a callable that returns a unique value for string inputs with # low chance of collision. The default is SHA256 base64. config.resource_cache_digest_function = Digest::SHA2.new.method(:base64digest) # Resource cache usage reporting # Optionally provide a callable which JSONAPI will call with information about cache # performance. Should accept three arguments: resource name, hits count, misses count. config.resource_cache_usage_report_function = nil end ```  ## Contributing  1. Fork it ( http://github.com/cerebris/jsonapi-resources/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  ### Running Tests  To run the tests for this project:  - `rake test` or `bundle exec rake test`  To run a single test:  - `bundle exec ruby -I test test/controllers/controller_test.rb -n test_type_formatting` ## License Copyright 2014-2016 Cerebris Corporation. MIT License (see LICENSE for details).