caprese 0.3.25 → 0.3.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 34252b10961eccda9b87897794f97016566a8e2d
-  data.tar.gz: f8b6e715a0cbbdbd9b71a81ef864872c09ab8aaa
+  metadata.gz: 1e98d646da7b21fc84de1e4e9c9954b0b67d0b94
+  data.tar.gz: e98309e9ef3b0d9102103dbd16670c69259793af
 SHA512:
-  metadata.gz: 289224faf57d9e726b555d8b10bf4114127f40d8469157f5320f7a30b6e5c01a7fdfeaf9802e61739beb4f6c2d966ead2fc7881c1ea99797c8e97ab2df2aecea
-  data.tar.gz: 525fb2eff4783c7f1c584db0ee9d4fb7ca2f0bd133661538d8ef28fb1f670898c631a965940c27b83190e86e0c29d081f4947afaa51f758de77b56cd82a33286
+  metadata.gz: 7c222c3c9ae7e98cd7ce548ba21a000e3c2a446cd31102b72720bfeb61a5d4eccab72d069055e28b79a41ef3fd70788251dcec1a36184c219b6481bb9b795596
+  data.tar.gz: 028fca901e3a6164720a8375618213560a42f81fa1c0331a528906e490c2cb39a81f178d23ce6be8775c472cb86ae1938615d4d949502660342b455c0212b97a

data/README.md

@@ -23,318 +23,445 @@ Or install it yourself as:
 
 ## Philosophy
 
-Caprese provides a controller framework that can automatically carry out `index`, `show`, `create`, `update`, and `destroy` actions for you with as little configuration as possible. You could write these methods yourself for every resource in your application, but the thing is, these 5 actions essentially do the same three things:
+Caprese provides a controller framework that can automatically carry out `index`, `show`, `create`, `update`, and `destroy` actions for you with as little configuration as possible. You could write these methods yourself for every resource in your API, but the thing is, these 5 actions essentially do the same three things:
 
 1. Find a resource or set of resources, based on the parameters provided
 2. Optionally apply a number of changes to them, based on the data provided and the action selected
 3. Serialize and respond with the resource(s), in the format that was requested
 
-Caprese does all of this dirty work for you, so all you have to do is customize its behavior to fine-tune the results. You customize the behavior by creating resource representations using serializers, by overriding intermediate helper methods, and by defining any number of callbacks in and around the actions to fully control each step of the process outlined above.
+Caprese does all of this dirty work for you, so all you have to do is customize its behavior to fine-tune the results. You customize the behavior using serializers, overriding methods, and defining any number of callbacks in and around the actions to fully control each step of the process outlined above.
 
-There are four components to creating an API using Caprese: controllers, routes, serializers, and records.
+In the real world, Caprese is a style of dish combining tomatoes, mozzarella, and basil pesto, and is usually put in a salad or on a sandwich. Just like the food, there are four components to creating an API using Caprese: models, serializers, controllers, routes.
 
-Before reading any further, we recommend that you read the [JSON API schema](http://jsonapi.org/format/) in full. It covers a lot of important information on all three steps above: modifying resource sets through query parameters, making changes to resources, modifying the response format, and more. Rather than make this doc a deep JSON API tutorial, we are going to assume you have read the schema and know what we're talking about.
+Let's create a working API endpoint using Caprese to do something useful: allowing users to create, read, update and delete sandwiches.
 
-## Usage
+## Building an API for sandwiches
 
-### Set up your controller structure
+### Prep the tomatoes (models)
 
-You are familiar with using `ApplicationController` and having your controllers inherit from it. In Caprese, your `ApplicationController` is a `Caprese::Controller`, and everything inherits from it:
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  include Caprese::Record
+end
 
-```
-# app/controllers/api/application_controller.rb
-module API
-  class ApplicationController < Caprese::Controller
-    # Global API configuration
-  end
+# == Schema Information
+#
+# Table name: sandwiches
+#
+#  id             :id               not null, primary key
+#  price          :decimal          not null
+#  description    :text
+#  size           :string(255)      not null
+#  restaurant_id  :integer          not null
+#
+class Sandwich < ApplicationRecord
+  belongs_to :restaurant
+
+  has_many :condiments
 end
 
-# app/controllers/api/v1/application_controller.rb
-module API
-  module V1
-    class ApplicationController < API::ApplicationController
-      # API V1 configuration
-    end
-  end
+# == Schema Information
+#
+# Table name: restaurants
+#
+#  id           :id               not null, primary key
+#  name         :string(255)      not null
+#
+class Restaurant < ApplicationRecord
+  has_many :sandwiches
+end
+
+# == Schema Information
+#
+# Table name: condiments
+#
+#  id            :id               not null, primary key
+#  name          :string(255)      not null
+#  serving_size  :integer          not null
+#  sandwich_id   :integer          not null
+#
+class Condiment < ApplicationRecord
+  belongs_to :sandwich
 end
 ```
 
-This structure allows you to define global API configuration, as well as versioned configuration specific to your `API::V1`.
+Tomatoes: Plain and hearty; an essential part of any true stack. The models of your application are just like them - you need them, but you can't consume them raw - your API has to decide what parts taste good for consumers. We say that models in Caprese are plain, because they're just Rails models...Caprese hasn't done much to them at all. So we create a `Sandwich` model with an association to a `Restaurant` and some `Condiment`s and then work on giving them a better taste with serializers.
 
-### Defining endpoints for a resource
+### Put on the mozzarella (serializers)
 
-Let's say you have a model `Product`. You'd create a versioned controller for it, inheriting from your `API::V1::ApplicationController`:
+```ruby
+class SandwichSerializer < Caprese::Serializer
+  attributes :price, :description, :size
 
-```
-# app/controllers/api/v1/products_controller.rb
-module API
-  module V1
-    class ProductsController < ApplicationController
-    end
-  end
+  belongs_to :restaurant
+
+  has_many :condiments
 end
-```
 
-You should also create a `Serializer` for `Product`, so Caprese will know what attributes to render in the response to requests.
+class RestaurantSerializer < Caprese::Serializer
+  attributes :name
+end
 
-Defining your serializers is simple:
+class CondimentSerializer < Caprese::Serializer
+  attributes :name, :serving_size
 
-```
-# app/serializers/api/v1/application_serializer.rb
-module API
-  module V1
-    class ApplicationSerializer < Caprese::Serializer
-      # API::V1 serializer configuration
-    end
-  end
+  belongs_to :sandwich
 end
+```
 
-# app/serializers/api/v1/product_serializer.rb
-module API
-  module V1
-    class ProductSerializer < ApplicationSerializer
-      attributes :title, :description
-    end
-  end
-end
+Mozzarella is so delicious - you can put it on anything and it's amazing. Mozzarella transforms the bland taste of tomatoes into something edible. Serializers are kinda the same way - you can use them to take a complex data model and turn it into something more consumable for people: JSON. When a user requests a sandwich from our API, Caprese will use the serializers above to define the fields (attributes and relationships) that the user sees, and by default, the response will look something like this:
+
+```json
+  {
+    "data": {
+      "type": "sandwiches",
+      "id": "1",
+      "attributes": {
+        "price": 10.0,
+        "description": "Tomato, mozzarella, and basil pesto between two pieces of bread.",
+        "size": "large"
+      },
+      "relationships": {
+        "condiments": {
+          "data": [
+            { "type": "condiments", "id": "5" },
+            { "type": "condiments", "id": "6" }
+          ]
+        },
+        "restaurant": {
+          "data": {
+            "type": "restaurants",
+            "id": "2"
+          }
+        }
+      }
+    }
+  }
 ```
 
-This tells Caprese that when rendering requests for products, it should only include the `product.title` and `product.description` in the response.
+*NOTE:* Caprese only includes resource identifiers (`type` and `id`) for the `condiments` and `restaurant` of the sandwich, or any other relationship for that matter. It does not include the fields (`attributes` and `relationships`) of these resources unless the user specifically requests them (see [this section of JSON API format](http://jsonapi.org/format/#fetching) for details).
 
-`Caprese::Serializer` inherits from `ActiveModel::Serializer`, thus leaving the functionality of serializers to be defined by [ActiveModelSerializers](https://github.com/rails-api/active_model_serializers), a powerful library in Rails API. `Caprese::Serializer` automatically creates `links` for both the resource itself, and *all* of the resource's relationships.
+### Bring the tomato and mozzarella together onto a sandwich or salad (controllers)
 
-From there, add a route:
+The bread of a sandwich or the leaves of a salad are what bring the entire Caprese dish together. Controllers are the same way - alongside tomatoes they are the "bite" of our application. When someone asks for a sandwich from our API, a controller fulfills the request, providing a necessary platform for that user to consume our tomatoes and mozzarella (the serialized resources). Let's bring our sandwich endpoint together with a controller, configuring it so it understands what information to use when creating a sandwich requested by a user:
 
-```
-# config/routes.rb
-Rails.application.routes.draw do
-  namespace 'api' do
-    namespace 'v1' do
-      caprese_resources :products
-    end
+```ruby
+class SandwichesController < Caprese::Controller
+  def permitted_create_params
+    [
+      :size, :condiments, :restaurant
+    ]
   end
 end
 ```
 
-With just that, you've just created fully functioning endpoints for `index`, `show`, and `destroy`:
+This means that when a user requests a sandwich, we will use the `size` of the sandwich, any `condiments`, as well as the `restaurant` that the user specified in order to create a new sandwich. Note that we don't include `price` and `description` - we don't want the user to be able to change these. The request that the user makes will look something like this:
 
+```json
+{
+  "data": {
+    "type": "sandwiches",
+    "attributes": {
+      "size": "small"
+    },
+    "relationships": {
+      "condiments": {
+        "data": [
+          { "type": "condiments", "id": "5" },
+          { "type": "condiments", "id": "6" },
+        ]
+      },
+      "restaurant": {
+        "data": {
+          "type": "restaurants",
+          "id": "1"
+        }
+      }
+    }
+  }
+}
 ```
-GET    /api/v1/products
-GET    /api/v1/products/:id
-DELETE /api/v1/products/:id
+
+You could also let the user create *new* condiments that aren't on the menu and put them onto their sandwich. Your controller would have to look like this:
+
+```ruby
+class SandwichesController < Caprese::Controller
+  def permitted_create_params
+    [
+      :size, :restaurant,
+      condiments: [:name, :serving_size]
+    ]
+  end
+end
 ```
 
-Make a request to any of these endpoints, and your response will be product(s) with their `title` and `description`.
+Now, the controller will look at the `name` and `serving_size` attributes of each condiment when creating the sandwich, and add each new condiment to the end result. The request the user would make would look like this:
 
-You can also modify the requests using JSON API query parameters like `filter`, `sort`, `page`, `limit`, `offset`, `fields`, and `includes`.
+```json
+{
+  "data": {
+    "type": "sandwiches",
+    "attributes": {
+      "size": "small"
+    },
+    "relationships": {
+      "condiments": {
+        "data": [
+          {
+            "type": "condiments",
+            "attributes": {
+              "name": "Dragon Blood",
+              "serving_size": "2"
+            }
+          },
+          {
+            "type": "condiments",
+            "attributes": {
+              "name": "Deep Fried Pickles",
+              "serving_size": "10"
+            }
+          }
+        ]
+      },
+      "restaurant": {
+        "data": {
+          "type": "restaurants",
+          "id": "1"
+        }
+      }
+    }
+  }
+}
+```
 
-You might ask: What about `create` and `update`? Well, those require some configuration in order to work:
+The response (outlined below) would contain the created sandwich along with any newly created condiments. Note that the attributes of the condiments that the user specified are not returned; remember that Caprese does not respond with `attributes` and `relationships` of related resources unless specifically told to do so.
 
+```json
+{
+  "data": {
+    "type": "sandwiches",
+    "id": "1",
+    "attributes": {
+      "price": 5.0,
+      "description": "Tomato, mozzarella, and basil pesto between two pieces of bread.",
+      "size": "small"
+    },
+    "relationships": {
+      "condiments": {
+        "data": [
+          { "type": "condiments", "id": "10" },
+          { "type": "condiments", "id": "11" },
+        ]
+      },
+      "restaurant": {
+        "data": {
+          "type": "restaurants",
+          "id": "1"
+        }
+      }
+    }
+  }
+}
 ```
-# app/controllers/api/v1/products_controller.rb
-module API
-  module V1
-    class ProductsController < ApplicationController
 
-      def permitted_create_params
-        [:title, :description]
-      end
+If you want users to be able to update sandwiches they've already created, you must also specify what they are allowed to update in the same manner as create:
 
-      def permitted_update_params
-        [:description]
-      end
+```ruby
+class SandwichesController < Caprese::Controller
+  def permitted_create_params
+    [
+      :size, :restaurant,
+      condiments: [:name, :serving_size]
+    ]
+  end
 
-    end
+  # Only allow users to change the condiments of their sandwich
+  #   1. Don't let them update the sandwich by creating new condiments, only specifying existing ones
+  #   2. Don't let them change the size or the restaurant
+  def permitted_update_params
+    [
+      :condiments
+    ]
   end
 end
 ```
 
-With that, you've stated that when creating a product, the params that are permitted to be assigned to the new product are `title` and `description`. When updating a product, the params that are permitted to be updated are nothing but `description`. You can't update the `title`.
+### Complete with a dollop of basil pesto (routes)
 
-That's it. You now have five fully functioning endpoints:
+All that's left to complete our sandwich API is to add routes for `index`, `show`, `create`, `update`, and `destroy`:
 
-```
-GET       /api/v1/products
-GET       /api/v1/products/:id
-POST      /api/v1/products
-PATCH/PUT /api/v1/products/:id
-DELETE    /api/v1/products/:id
+```ruby
+Rails.application.routes.draw do
+  caprese_resources :sandwiches
+end
 ```
 
-### Managing relationships of resources
-
-The above is a little misleading. After doing the steps above, you'll actually end up with EIGHT endpoints:
+With that, you'll now be able to make requests to any of the following URLs, and assuming you provide the necessary data, each one will provide a working response.
 
 ```
-GET       /api/v1/products
-GET       /api/v1/products/:id
-POST      /api/v1/products
-PATCH/PUT /api/v1/products/:id
-DELETE    /api/v1/products/:id
-GET       /api/v1/products/:id/:relationship
-GET       /api/v1/products/:id/relationships/:relationship
-PATCH/PUT/DELETE /api/v1/products/:id/relationships/:relationship
+GET        /sandwiches
+GET        /sandwiches/:id
+POST       /sandwiches
+PATCH/PUT  /sandwiches/:id
+DELETE     /sandwiches/:id
 ```
 
-The three new endpoints are for reading and managing relationships (known as `associations` in Rails) of the resource.
-
-You can also specify which relationships can be assigned to a resource when created or which relationships can be updated:
+Additionally, Caprese provides four routes that can be used to manage the relationships of the sandwich directly:
 
 ```
-def permitted_create_params
-  [:title, :description]
-end
-
-def permitted_update_params
-  [:description, :orders]
-end
+GET        /sandwiches/:id/:relationship
+GET        /sandwiches/:id/relationships/:relationship
+PATCH/PUT  /sandwiches/:id/relationships/:relationship
+DELETE     /sandwiches/:id/relationships/:relationship
 ```
 
-You could thus update the orders of a product in by making a call to one of two endpoints:
-```
-PATCH/PUT         /api/v1/products/:id                      # include `orders` in `relationships` member
-PATCH/POST/DELETE /api/v1/products/:id/relationships/orders # provide resource identifiers for orders
+For example, one could make a request to `GET /sandwiches/1/condiments` and the response would be like so:
+
+```json
+{
+  "data": [
+    {
+      "type": "condiments",
+      "id": "5",
+      "attributes": {
+        "name": "Ketchup",
+        "serving_size": "2"
+      },
+      "relationships": {
+        "sandwich": {
+          "data": { "type": "sandwiches", "id": "1" }
+        }
+      }
+    },
+    {
+      "type": "condiments",
+      "id": "6",
+      "attributes": {
+        "name": "Mustard",
+        "serving_size": "1"
+      },
+      "relationships": {
+        "sandwich": {
+          "data": { "type": "sandwiches", "id": "1" }
+        }
+      }
+    }
+  ]
+}
 ```
 
-### Scoping resources to customize behavior
+For all the details about using relationship endpoints, see [this section](http://jsonapi.org/format/#fetching-relationships) and [this section](http://jsonapi.org/format/#crud-updating-relationships) of the JSON API format.
 
-Let's say you don't want a user to be able to request all the products in your database, you only want them to be able to request the ones that belong to them. If you determined `current_user` based on the authentication credentials they used, you could scope your products to only `current_user` by overriding the intermediate helper method `record_scope`:
+## Customizing the sandwich further
 
-```
-# app/controllers/api/v1/products_controller.rb
-module API
-  module V1
-    class ProductsController < ApplicationController
-      def record_scope(type)
-        case type
-        when :products
-          Product.where(user: current_user)
-        end
-      end
-    end
-  end
-end
-```
+### Scoping resources
 
-Let's take that one step further and state that when that user updates the orders of an existing product, you only want them to be able to add orders that belong to them, too. Simple:
+Let's say your sandwich API can create sandwiches for users from 5 different restaurants. Each restaurant has its own condiments, and you want to ensure that a customer cannot request a condiment from a restaurant if the restaurant does not have it.
+
+By default, when `SandwichesController` looks for `condiments`, it uses `Condiment.all` as a starting point. This means that your user making a request could definitely request a condiment that does not exist at the restaurant they're ordering from. To fix this, we use a helper called `record_scope`:
 
 ```
-def record_scope(type)
-  case type
-  when :products
-    Product.where(user: current_user)
-  when :orders
-    Order.where(user: current_user)
+class SandwichesController < ApplicationController
+  def record_scope(type)
+    case type
+    when :condiments
+      Condiment.where(restaurant_id: data[:relationships][:restaurant][:data][:id])
+    else
+      super
+    end
   end
 end
 ```
 
-Now, if they were to make a request like `POST /api/v1/products/1/relationships/orders` to append an order to one of their products, and they submit a resource identifier for an order that did not belong to them, the response would be `404 Not Found`.
+### Scoping relationships
+
+Let's say you've created endpoints for `restaurants` as well, using the steps outlined above. This means that a user could make a request like `GET /restaurants/1/sandwiches` and the response would be all the sandwiches that the restaurant has created.
 
-There is one more consideration to be made here. What if, when this user makes a request to `GET /api/v1/products/1/orders` to get the list of orders for one of their products, you only want to return orders that have been created in the last week. This time, you override another intermediate helper method, `relationship_scope`:
+What if, instead, you wanted this endpoint to only return sandwiches that the restaurant had created in the last week alone. Simple, use `relationship_scope`:
 
 ```
-def relationship_scope(name, scope)
-  case name
-  when :orders
-    scope.where('created_at < ?', 1.week.ago)
+class RestaurantsController < ApplicationController
+  def relationship_scope(name, scope)
+    case name
+    when :sandwiches
+      scope.where('created_at < ?', 1.week.ago)
+    else
+      super
+    end
   end
 end
 ```
 
-`name` is the name of the relationship to scope, and `scope` is the existing scope for the relationship, in this case, equal to `Product.find(1).orders`.
-
 ### Modifying control flow with callbacks
 
-You may want to customize the behavior of an action, but you don't want to go about the task of overriding it entirely. Caprese defines a number of callbacks to modify the control flow for any action, allowing you to keep controller logic where it belongs.
-
-```
-# app/controllers/api/v1/orders_controller.rb
-module API
-  module V1
-    class OrdersController < ApplicationController
-      after_initialize :calculate_price_from_line_items, :do_something_else
-      after_create :send_confirmation_email
-
-      private
-
-      # If `Order#line_items` is a has_many association, and is created with an order (see: nested association creation),
-      # iterate over each line item and sum its price to determine the total order price
-      def calculate_price_from_line_items(order)
-        if order.line_items.any?
-          order.price = order.line_items.inject(0) do |sum, li|
-            sum += li.price
-          end
-        else
-          order.errors.add(:line_items, :blank) # an order must have line items
-        end
-      end
-
-      # After creating an order, send the customer a confirmation email
-      def send_confirmation_email(order)
-        ConfirmationMailer.send(order)
-      end
-    end
-  end
-end
-```
-
-The following callbacks are defined by Caprese:
+You may want to customize the behavior of an action like `create`, `update`, or `delete`, but you don't want to go about the task of overriding it entirely. Caprese defines a number of callbacks to modify the control flow for these actions:
 
 ```
-before_query        (called before anything)
-after_query         (called after the response is rendered)
-after_initialize    (called in #create after the resource is instantiated)
+after_initialize
 before_create       (alias for after_initialize)
-after_create        (rest are self explanatory)
+after_create
 before_update
 after_update
-before_save
-after_save
+before_save         (called before `create` and `update`)
+after_save          (ditto, but after)
 before_destroy
 after_destroy
 ```
 
-Reading this, note that saying `before_action :do_something, only: [:create]` is not the same as saying `before_create :do_something`. But you can use the former if you like, to customize further.
+To implement one of these callbacks, simply define a callback method and add it to a callback list:
 
-### Creating nested associations
+```
+class SandwichesController < ApplicationController
+  before_create :cut_bread
+  before_save :calculate_price_from_special_condiments
+  after_update :refund_payment_method_if_moldy
 
-You can also use Caprese to created nested associations when creating their owners. For example, if I have two models:
+  private
 
-```
-class Order < ActiveRecord::Base
-  has_many :line_items, autosave: true
+  # Call custom method Sandwich#cut_bread before creating the sandwich
+  def cut_bread(sandwich)
+    sandwich.cut_bread
+  end
+
+  # If any of the condiments is avocado, add extra price when creating and updating sandwiches
+  def calculate_price_from_special_condiments(sandwich)
+    if(avocado = sandwich.condiments.detect { |c| c.is_a?(Avocado) })
+      sandwich.price += avocado.special_price
+    end
+  end
+
+  # If the customer updates us and says the sandwich is moldy, refund the sandwich
+  def refund_payment_method_if_moldy(sandwich)
+    sandwich.refund if sandwich.moldy?
+  end
 end
+```
+
+### Handling errors
+
+Errors in Caprese come in two forms: model errors, and controller errors.
+
+#### Model Errors
 
-class LineItem < ActiveRecord::Base
-  belongs_to :order
+Model errors are created when a record does not pass validation. [Validators are defined in the model using standard Rails.](http://guides.rubyonrails.org/active_record_validations.html) For example:
+
+```
+class Sandwich < ApplicationRecord
+  validates_presence_of :size
+  validates_length_of :condiments, minimum: 2
 end
 ```
 
-I can send a resource document to `POST /api/v1/orders` that looks like this:
+If a user were to make a request like so:
 
 ```json
 {
   "data": {
-    "type": "orders",
-    "attributes": {
-      "some_order_attribute": "..."
-    },
+    "type": "sandwiches",
     "relationships": {
-      "line_items": {
+      "condiments": {
         "data": [
-          {
-            "type": "line_items",
-            "attributes": {
-              "price": 5.0
-            }
-          },
-          {
-            "type": "line_items",
-            "attributes": {
-              "price": 6.0
-            }
-          }
+          { "type": "condiments", "id": "1" }
         ]
       }
     }
@@ -342,48 +469,20 @@ I can send a resource document to `POST /api/v1/orders` that looks like this:
 }
 ```
 
-and once I configure my controller to indicate that it is permitted to create line items with orders, it will work:
-
-```
-# app/controllers/api/v1/orders_controller.rb
-module API
-  module V1
-    class OrdersController < ApplicationController
-      def permitted_create_params
-        [:some_order_attribute, line_items: [:price]]
-      end
-    end
-  end
-end
-```
-
-You could apply the same logic to `permitted_update_params` to update line items through `PATCH /api/v1/orders/:id`, just add an `"id"` field to the relationship data of each line item so Caprese knows which one to update.
-
-### Handling errors
-
-Errors in Caprese come in two forms: model errors, and controller errors.
-
-#### Model Errors
-
-Model errors are returned from the server looking like this:
+The server would respond with `422 Unprocessable Entity`, with a response body like so:
 
 ```json
 {
   "errors": [
     {
-      "source": { "pointer": "/data/attributes/price" },
-      "code": "blank",
-      "detail": "Price cannot be blank."
-    },
-    {
-      "source": { "pointer": "/data/relationships/line_items" },
+      "source": { "pointer": "/data/attributes/size" },
       "code": "blank",
-      "detail": "Line items cannot be blank."
+      "detail": "Size cannot be blank."
     },
     {
-      "source": { "pointer": "/data/relationships/line_items/data/attributes/price" },
+      "source": { "pointer": "/data/relationships/condiments" },
       "code": "blank",
-      "detail": "Price cannot be blank."
+      "detail": "Condiments must be of length 2 or more."
     }
   ]
 }
@@ -391,33 +490,37 @@ Model errors are returned from the server looking like this:
 
 Model errors have the same interface as in ActiveRecord, but with some added functionality on top. ActiveRecord errors only contain a message (for example: `price: 'Price cannot be blank'`). Caprese model errors also have a code (for example: `price: { code: :blank, message: 'Price cannot be blank.' }`), which is a much more programmatic solution. Rails 5 fixes this, but since Caprese supports both Rails 4 and Rails 5, we defined our own functionality for the time being.
 
-To make use of Caprese model errors, add the `Caprese::Record` concern to your models:
-
-```
-class Product < ActiveRecord::Base
-  include Caprese::Record
-end
-```
+The other thing that `Caprese::Record` brings to the table is that it allows you to create separate translations for error messages depending on the context: API, or application. Application is what you're used to. You can define a translation like `en.active_record.errors.models.product.attributes.title.blank = 'Hey buddy, a product title can't be blank!'` and that user-friendly error message is what will show up in your application form and other user interfaces. But using the same layperson user-friendly error message to a third party API developer is kinda weird, and maybe not so useful.
 
-The other thing that `Caprese::Record` brings to the table is that it allows you to create separate translations for error messages depending on the context: API, or application. Application is what you're used to. You can define a translation like `en.active_record.errors.models.product.attributes.title.blank = 'Hey buddy, a product title can't be blank!'` and that user-friendly error message is what will show up in your application. But using the same user-friendly error message to a third party API developer is kinda weird.
+To use your own errors, set `Caprese.config.i18n_scope = '[YOUR_SCOPE]'`
 
-You can define your own set of translations specifically for your API: `en.api.v1.errors.models.product.title.blank = 'Custom error message'`. This requires some configuration on your part. You have to tell Caprese where to look by setting `Caprese.config.i18n_scope = 'api.v1.errors'`
+You can define your own set of translations specifically for your API: `en.[YOUR_SCOPE].models.product.title.blank = 'Custom error message'`. This requires some configuration on your part.
 
 Caprese looks for translations in the following order, and if none of them are defined, it will use `code.to_s` as the error message:
 
 ```
 # for field errors (attribute or relationship)
-api.v1.errors.models.[model_name].[field].[code]
-api.v1.errors.field.[code]
-api.v1.errors.[code]
+[YOUR_SCOPE].models.[model_name].[field].[code]
+[YOUR_SCOPE].field.[code]
+[YOUR_SCOPE].[code]
 
 # for errors on base
-api.v1.errors.models.[model_name].[code]
-api.v1.errors.[code]
+[YOUR_SCOPE].models.[model_name].[code]
+[YOUR_SCOPE].[code]
 ```
 
 #### Controller errors
 
+Caprese provides a method to create controller errors that can have their own translation scope. If at any point in your control flow, say in a callback, you want to immediately halt the request and respond with an error message, you can do the following:
+
+```
+fail error(
+  field: :filter,
+  code: :invalid,
+  t: { ... } # translation interpolation variables to use in the error message
+)
+```
+
 Controller errors are returned from the server looking like this:
 
 ```json
@@ -432,45 +535,16 @@ Controller errors are returned from the server looking like this:
 }
 ```
 
-Caprese provides a helper method to easily create controller errors that can have their own translation scope. If at any point in your control flow, say in a callback, you want to immediately halt the request and respond with an error message, you can do the following:
-
-```
-fail error(
-  field: :filter,
-  code: :invalid,
-  t: { ... } # translation interpolation variables to use in the error message
-)
-```
-
-Caprese will search for controller errors in the following order, and if none of them are defined, it will use `code.to_s` as the error message:
-
-```
-api.v1.errors.controllers.[controller].[action].[field].[code]
-api.v1.errors.controllers.[controller].[action].[code]
-api.v1.errors.[code]
-```
-
-#### Customizing your error and error message
-
-The raw error object for Caprese is as follows:
+Caprese will search for controller errors in the following order:
 
 ```
-fail Error.new(
-  model: ...,      # model name
-  controller: ..., # only model name || controller && action should be provided, not both
-  action: ...,
-  field: ...,
-  code: :invalid,
-  t: { ... }       # translation interpolation variables to use in the error message
-)
+[YOUR_SCOPE].controllers.[controller].[action].[field].[code]
+[YOUR_SCOPE].controllers.[controller].[action].[code]
+[YOUR_SCOPE].[code]
 ```
 
-Two translation interpolation variables will be provided for you automatically, on top of whatever ones you pass in. Those two are: `%{field}` and `%{field_title}`. If `field == :my_title`, `%{field} == my_title` and `%{field_title} == My Title`
-
 ### Configuration
 
-As a guide to configuring Caprese, here is the portion of `lib/caprese.rb` that stores the defaults:
-
 ```
 # Defines the primary key to use when querying records
 config.resource_primary_key ||= :id

data/lib/caprese/adapter/json_api/json_pointer.rb

@@ -34,15 +34,11 @@ module Caprese
             values = value.to_s.split('.')
             last_index = values.count - 1
 
+            klass_iteratee = record.class
             values.each_with_index.inject('') do |pointer, (v, i)|
               pointer +
-                if record.class.reflections.key?(v)
-                  record =
-                    if record.class.reflections[v].collection?
-                      record.send(v).first
-                    else
-                      record.send(v)
-                    end
+                if ref = (klass_iteratee.reflect_on_association(v) || klass_iteratee.reflect_on_association(klass_iteratee.caprese_unalias_field(v)))
+                  klass_iteratee = ref.klass
 
                   if i == last_index
                     format(POINTERS[:relationship_base], v)

data/lib/caprese/controller/concerns/aliasing.rb

@@ -5,6 +5,31 @@ module Caprese
   module Aliasing
     extend ActiveSupport::Concern
 
+    # Records all of the field aliases engaged by the API request (called in `assign_record_attributes` using comparison)
+    # so that when the response is returned, the appropriate alias is used in reference to fields
+    #
+    # Success: @todo
+    # Errors: @see ErrorSerializer
+    #
+    # @example
+    # {
+    #   aliased_attribute: true, # used aliased attribute name instead of unaliased one
+    #
+    #   aliased_relationship: { # used aliased relationship name
+    #     aliased_attribute: true # and aliased attribute names
+    #     aliased_attribute_2: true
+    #   },
+    #
+    #   aliased_relationship: {}, # used aliased relationship name but no aliased attribute names
+    #
+    #   unaliased_relationship: { # used unaliased relationship name
+    #     aliased_attribute: true # and aliased attribute name for that relationship
+    #   },
+    # }
+    def engaged_field_aliases
+      @__engaged_field_aliases ||= {}
+    end
+
     # Specifies specific resource models that have types that are aliased.
     # @note The `caprese_type` class variable of the model should also be set to the new type
     # @example

data/lib/caprese/controller/concerns/persistence.rb

@@ -19,7 +19,7 @@ module Caprese
       end
 
       rescue_from ActiveRecord::RecordInvalid do |e|
-        rescue_with_handler RecordInvalidError.new(e.record)
+        rescue_with_handler RecordInvalidError.new(e.record, engaged_field_aliases)
       end
 
       rescue_from ActiveRecord::RecordNotDestroyed do |e|
@@ -46,7 +46,7 @@ module Caprese
       execute_before_create_callbacks(record)
       execute_before_save_callbacks(record)
 
-      fail RecordInvalidError.new(record) if record.errors.any?
+      fail RecordInvalidError.new(record, engaged_field_aliases) if record.errors.any?
 
       record.save!
 
@@ -75,7 +75,7 @@ module Caprese
       execute_before_update_callbacks(queried_record)
       execute_before_save_callbacks(queried_record)
 
-      fail RecordInvalidError.new(queried_record) if queried_record.errors.any?
+      fail RecordInvalidError.new(queried_record, engaged_field_aliases) if queried_record.errors.any?
 
       queried_record.save!
 
@@ -219,17 +219,34 @@ module Caprese
     # @param [ActiveRecord::Base] record the record to build attribute into
     # @param [Array] permitted_params the permitted params for the action
     # @param [Parameters] data the data sent to the server to construct and assign to the record
-    def assign_record_attributes(record, permitted_params, data)
-      attributes = data[:attributes].try(:permit, *permitted_params).try(:inject, {}) do |out, (attr, val)|
-        out[actual_field(attr, record.class)] = val
+    # @option [String] parent_relationship_name the parent relationship assigning these attributes to the record, used to determine
+    #   engaged aliases @see concerns/aliasing
+    def assign_record_attributes(record, permitted_params, data, parent_relationship_name: nil)
+      # TODO: Make safe by enforcing that only a single alias/unalias can be engaged at once
+      engaged_field_aliases_object = parent_relationship_name ? (engaged_field_aliases[parent_relationship_name] ||= {}) : engaged_field_aliases
+
+      attributes = data[:attributes].try(:permit, *permitted_params).try(:inject, {}) do |out, (attribute_name, val)|
+        attribute_name = attribute_name.to_sym
+        actual_attribute_name = actual_field(attribute_name, record.class)
+
+        if attribute_name != actual_attribute_name
+          engaged_field_aliases_object[attribute_name] = true
+        end
+
+        out[actual_attribute_name] = val
         out
       end || {}
 
       data[:relationships]
       .try(:slice, *flattened_keys_for(permitted_params))
       .try(:each) do |relationship_name, relationship_data|
+        relationship_name = relationship_name.to_sym
         actual_relationship_name = actual_field(relationship_name, record.class)
 
+        if relationship_name != actual_relationship_name
+          engaged_field_aliases_object[relationship_name] = {}
+        end
+
         # TODO: Add checkme for relationship_name to ensure that format is correct (not Array when actually Record, vice versa)
         #   No relationship exists as well
 
@@ -261,19 +278,24 @@ module Caprese
           ref = record_for_relationship(owner, relationship_name, relationship_data_item)
 
           if ref && contains_constructable_data?(relationship_data_item)
-            assign_record_attributes(ref, permitted_params, relationship_data_item)
+            assign_record_attributes(ref, permitted_params, relationship_data_item, parent_relationship_name: relationship_name)
           end
 
           ref
         end
-      else
+      elsif relationship_data[:data].present?
         ref = record_for_relationship(owner, relationship_name, relationship_data[:data])
 
         if ref && contains_constructable_data?(relationship_data[:data])
-          assign_record_attributes(ref, permitted_params, relationship_data[:data])
+          assign_record_attributes(ref, permitted_params, relationship_data[:data], parent_relationship_name: relationship_name)
         end
 
         ref
+      else
+        raise Error.new(
+          field: "/data/relationships/#{relationship_name}/data",
+          code: :blank
+        )
       end
     end
 
@@ -314,19 +336,6 @@ module Caprese
       end
     end
 
-    # Assigns permitted attributes for a record in a relationship, for a given action
-    # like create/update
-    #
-    # @param [ActiveRecord::Base] record the relationship record
-    # @param [String] relationship_name the name of the relationship
-    # @param [Symbol] action the action that is calling this method (create, update)
-    # @param [Hash] resource_identifier the resource identifier
-    def assign_relationship_record_attributes(record, relationship_name, action, attributes)
-      record.assign_attributes(
-        attributes.permit(nested_permitted_params_for(action, relationship_name))
-      )
-    end
-
     # Indicates whether or not :attributes or :relationships keys are in a resource identifier,
     # thus allowing us to construct this data into the final record
     #

data/lib/caprese/controller/concerns/relationships.rb

@@ -24,6 +24,25 @@ module Caprese
       scope
     end
 
+    # Allows selection of serializer for any relationship serialized by get_relationship_data
+    #
+    # @note Returns nil by default because Caprese::Controller#render will determine the serializer if nil
+    #
+    # @example
+    #   def relationship_serializer(name)
+    #     case name
+    #     when :answer
+    #       AnswerSerializer
+    #     else
+    #       super
+    #     end
+    #   end
+    # @param [String] name the name of the relationship
+    # @return [Serializer,Nil] the serializer for the relationship or nil if none specified
+    def relationship_serializer(name)
+      nil
+    end
+
     # Retrieves the data for a relationship, not just the definition/resource identifier
     #   @note Resource Identifier = { id: '...', type: '....' }
     #   @note Resource = Resource Identifier + { attributes: { ... } }
@@ -44,7 +63,7 @@ module Caprese
     def get_relationship_data
       target =
         if queried_association.reflection.collection?
-          scope = relationship_scope(params[:relationship], queried_association.reader)
+          scope = relationship_scope(params[:relationship].to_sym, queried_association.reader)
 
           if params[:relation_primary_key_value].present?
             get_record!(scope, self.class.config.resource_primary_key, params[:relation_primary_key_value])
@@ -57,18 +76,23 @@ module Caprese
 
       links = { self: request.original_url }
 
-      if !target.respond_to?(:to_ary) &&
-        url_helpers.respond_to?(related_url = version_name("#{params[:relationship].singularize}_url"))
+      if target.respond_to?(:to_ary)
+        serializer_type = :each_serializer
+      else
+        serializer_type = :serializer
 
-        links[:related] =
-          url_helpers.send(
-            related_url,
-            target.read_attribute(self.config.resource_primary_key),
-            host: caprese_default_url_options_host
-          )
+        if url_helpers.respond_to?(related_url = version_name("#{params[:relationship].singularize}_url"))
+          links[:related] =
+            url_helpers.send(
+              related_url,
+              target.read_attribute(self.config.resource_primary_key),
+              host: caprese_default_url_options_host
+            )
+        end
       end
 
       render(
+        serializer_type => relationship_serializer(params[:relationship].to_sym),
         json: target,
         fields: query_params[:fields],
         include: query_params[:include],
@@ -231,7 +255,7 @@ module Caprese
           when :has_one
             if request.patch?
               queried_record.send("#{relationship_name}=", relationship_resources[0])
-              objects[0].save
+              relationship_resources[0].save if relationship_resources[0].present?
             end
           when :belongs_to
             if request.patch?

data/lib/caprese/controller/concerns/typing.rb

@@ -50,7 +50,7 @@ module Caprese
         invalid_typed_record = controller_record_class.new
         invalid_typed_record.errors.add(:type)
 
-        fail RecordInvalidError.new(invalid_typed_record)
+        fail RecordInvalidError.new(invalid_typed_record, engaged_field_aliases)
       end
     end
   end

data/lib/caprese/errors.rb

@@ -5,11 +5,12 @@ module Caprese
   #
   # @param [ActiveRecord::Base] record the record that is invalid
   class RecordInvalidError < Error
-    attr_reader :record
+    attr_reader :record, :aliases
 
-    def initialize(record)
+    def initialize(record, engaged_field_aliases = {})
       super()
       @record = record
+      @aliases = engaged_field_aliases
       @header = { status: :unprocessable_entity }
     end
 

data/lib/caprese/record/errors.rb

@@ -24,7 +24,7 @@ module Caprese
 
         e = Error.new(
           model: @base.class.name.underscore.downcase,
-          field: attribute == :base ? nil : @base.class.caprese_alias_field(attribute),
+          field: attribute == :base ? nil : attribute,
           code: code,
           t: options[:t]
         )
@@ -56,7 +56,7 @@ module Caprese
         (get(attribute) || []).map { |e| e.full_message }
       end
 
-      # @note Overriden because traditionally to_a is an alias for `full_messages`, because in Rails standard there is
+      # @note Overridden because traditionally to_a is an alias for `full_messages`, because in Rails standard there is
       #   no difference between an error and a full message, an error is that full message. With our API, an error is a
       #   model that can render full messages, but it is still a distinct model. `to_a` thus has a different meaning here
       #   than in Rails standard.

data/lib/caprese/serializer/concerns/lookup.rb

@@ -11,12 +11,14 @@ module Caprese
         # @note Overrides the AMS default since the default does not do namespaced lookup
         #
         # @param [ActiveRecord::Base] record the record to get a serializer for
-        # @param [Hash] options options for `super` to use when getting the serializer
+        # @param [Hash] options options to use when getting the serializer
         # @return [Serializer,Nil] the serializer for the given record
         def serializer_for(record, options = {})
           return ActiveModel::Serializer::CollectionSerializer if record.respond_to?(:to_ary)
 
-          get_serializer_for(record.class) if valid_for_serialization(record)
+          if valid_for_serialization(record)
+            options.fetch(:serializer) { get_serializer_for(record.class) }
+          end
         end
 
         # Indicates whether or not the record specified can be serialized by Caprese

data/lib/caprese/serializer/error_serializer.rb

@@ -3,11 +3,68 @@ require 'caprese/serializer'
 module Caprese
   class Serializer
     class ErrorSerializer < ActiveModel::Serializer::ErrorSerializer
-      delegate :as_json, to: :object
-
       def resource_errors?
         object.try(:record).present?
       end
+
+      # Applies aliases to fields of RecordInvalid record's errors if aliases have been applied
+      # @see controller/concerns/aliasing#engaged_field_aliases
+      # Otherwise returns normal error fields as_json hash
+      def as_json
+        json = object.as_json
+
+        record = object.try(:record)
+        aliases = object.try(:aliases)
+
+        if record.present? && aliases.try(:any?)
+          aliased_json = {}
+
+          json.each do |k, v|
+            # Iterate over engaged_field_aliases object and see if each segment of the name split by '.' is in it (meaning
+            # that segment should be aliased for the error output since that is what the user is expecting)
+            klass_iterator = record.class
+            alias_iterator = aliases
+
+            field_iteratee = k.to_s.split('.')
+            new_error_field_name =
+              field_iteratee.map do |field|
+                field_alias = klass_iterator.caprese_alias_field(field)
+
+                if i = alias_iterator.try(:[], field_alias)
+                  alias_iterator = i
+
+                  # If != true, will be an object (relationship) to traverse, find the relationship klass so we can use its aliases
+                  # for the next segment of alias_iterator
+                  if alias_iterator != true && (ref = klass_iterator.reflect_on_association(field)).present?
+                    klass_iterator = ref.klass
+                  end
+
+                  field_alias
+                elsif i = alias_iterator.try(:[], field)
+                  alias_iterator = i
+
+                  # If != true, will be an object (relationship) to traverse, find the relationship klass so we can use its aliases
+                  # for the next segment of alias_iterator
+                  if alias_iterator != true && (ref = klass_iterator.reflect_on_association(field)).present?
+                    klass_iterator = ref.klass
+                  end
+
+                  field
+                else
+                  alias_iterator = {}
+
+                  field
+                end
+              end
+
+            aliased_json[new_error_field_name.join('.')] = v
+          end
+
+          aliased_json
+        else
+          json
+        end
+      end
     end
   end
 end

data/lib/caprese/version.rb

@@ -1,3 +1,3 @@
 module Caprese
-  VERSION = '0.3.25'
+  VERSION = '0.3.26'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: caprese
 version: !ruby/object:Gem::Version
-  version: 0.3.25
+  version: 0.3.26
 platform: ruby
 authors:
 - Nick Landgrebe
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-05-30 00:00:00.000000000 Z
+date: 2017-08-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: active_model_serializers