caprese 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0f662bf206bc10125464b9779d47c1d6704e0062
-  data.tar.gz: cd8f888d31eed365bc32e9efeb762903c04780b9
+  metadata.gz: 6fa772365d2becc2bae5be4328595931ffee6107
+  data.tar.gz: 9d2aee61283a8abd50d736b48bd255ab73e5f0b8
 SHA512:
-  metadata.gz: 85b15e24d4f7f89d67d4741dd1e3d47d0ecf90414a6ce0e6b1499a24aa0d3f58b8aec2e8e47270c1c0e5d82d5cedd11f0525dfe9a4761a263ea2290d1a15cbe7
-  data.tar.gz: a1c2e81f96bce6b52c80c7ca61aed31018121a542b9baa67c819ec9c66565495ee96d434211128cb6cc75399682a251be3d742764e8ab8a9c7bc4d8496006e8d
+  metadata.gz: d23e29b6a9f9f5933350566da1f199c15cb4537320d235a11377147154b80dc9a789b658b59b43ef88a264a97f65bf1a7a0631f2962b1e71c813339887423459
+  data.tar.gz: 70b9ba12711fcdf36b4d9834a11d5bfc2cb763855d2e5115bf2f94c920085cb52bbf306e62a5ad8e38dac114eb0b51dd8e20e380f050c6607a7379bb1cf871af

data/README.md

@@ -1,9 +1,9 @@
 # Caprese
 
 Caprese is a Rails library for creating RESTful APIs in as few words as possible. It handles all CRUD operations on resources and their associations for you, and you can customize how these operations
-are carried out by overriding intermediate helper methods and by defining callbacks around any CRUD action.
+are carried out, allowing for infinite possibilities while focusing on work that matters to you, instead of writing repetitive code for each action of each resource in your application.
 
-What separates Caprese from similar gems is that it is trying to do as little as possible, instead allowing gems that are better at other things to do what they are good at, as opposed to Caprese trying to do it all.
+For now, the only format that is supported by Caprese is the [JSON API schema](http://jsonapi.org/format/). In the future, Caprese will support a more straightforward (but less powerful) JSON format as well, for simpler use cases.
 
 ## Installation
 
@@ -21,9 +21,481 @@ Or install it yourself as:
 
     $ gem install caprese
 
+## 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:
+
+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.
+
+There are four components to creating an API using Caprese: controllers, routes, serializers, and records.
+
+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.
+
 ## Usage
 
-TODO: Write usage instructions here
+### Set up your controller structure
+
+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:
+
+```
+# app/controllers/api/application_controller.rb
+module API
+  class ApplicationController < Caprese::Controller
+    # Global API configuration
+  end
+end
+
+# app/controllers/api/v1/application_controller.rb
+module API
+  module V1
+    class ApplicationController < API::ApplicationController
+      # API V1 configuration
+    end
+  end
+end
+```
+
+This structure allows you to define global API configuration, as well as versioned configuration specific to your `API::V1`.
+
+### Defining endpoints for a resource
+
+Let's say you have a model `Product`. You'd create a versioned controller for it, inheriting from your `API::V1::ApplicationController`:
+
+```
+# app/controllers/api/v1/products_controller.rb
+module API
+  module V1
+    class ProductsController < ApplicationController
+    end
+  end
+end
+```
+
+You should also create a `Serializer` for `Product`, so Caprese will know what attributes to render in the response to requests.
+
+Defining your serializers is simple:
+
+```
+# app/serializers/api/v1/application_serializer.rb
+module API
+  module V1
+    class ApplicationSerializer < Caprese::Serializer
+      # API::V1 serializer configuration
+    end
+  end
+end
+
+# app/serializers/api/v1/product_serializer.rb
+module API
+  module V1
+    class ProductSerializer < ApplicationSerializer
+      attributes :title, :description
+    end
+  end
+end
+```
+
+This tells Caprese that when rendering requests for products, it should only include the `product.title` and `product.description` in the response.
+
+`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.
+
+From there, add a route:
+
+```
+# config/routes.rb
+Rails.application.routes.draw do
+  namespace 'api' do
+    namespace 'v1' do
+      caprese_resources :products
+    end
+  end
+end
+```
+
+With just that, you've just created fully functioning endpoints for `index`, `show`, and `destroy`:
+
+```
+GET    /api/v1/products
+GET    /api/v1/products/:id
+DELETE /api/v1/products/:id
+```
+
+Make a request to any of these endpoints, and your response will be product(s) with their `title` and `description`.
+
+You can also modify the requests using JSON API query parameters like `filter`, `sort`, `page`, `limit`, `offset`, `fields`, and `includes`.
+
+You might ask: What about `create` and `update`? Well, those require some configuration in order to work:
+
+```
+# app/controllers/api/v1/products_controller.rb
+module API
+  module V1
+    class ProductsController < ApplicationController
+
+      def permitted_create_params
+        [:title, :description]
+      end
+
+      def permitted_update_params
+        [:description]
+      end
+
+    end
+  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`.
+
+That's it. You now have five fully functioning endpoints:
+
+```
+GET       /api/v1/products
+GET       /api/v1/products/:id
+POST      /api/v1/products
+PATCH/PUT /api/v1/products/:id
+DELETE    /api/v1/products/:id
+```
+
+### Managing relationships of resources
+
+The above is a little misleading. After doing the steps above, you'll actually end up with EIGHT endpoints:
+
+```
+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
+```
+
+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:
+
+```
+def permitted_create_params
+  [:title, :description]
+end
+
+def permitted_update_params
+  [:description, :orders]
+end
+```
+
+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
+```
+
+### Scoping resources to customize behavior
+
+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`:
+
+```
+# 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
+```
+
+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:
+
+```
+def record_scope(type)
+  case type
+  when :products
+    Product.where(user: current_user)
+  when :orders
+    Order.where(user: current_user)
+  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`.
+
+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`:
+
+```
+def relationship_scope(name, scope)
+  case name
+  when :orders
+    scope.where('created_at < ?', 1.week.ago)
+  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:
+
+```
+before_query        (called before anything)
+after_query         (called after the response is rendered)
+after_initialize    (called in #create after the resource is instantiated)
+before_create       (alias for after_initialize)
+after_create        (rest are self explanatory)
+before_update
+after_update
+before_save
+after_save
+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.
+
+### Creating nested associations
+
+You can also use Caprese to created nested associations when creating their owners. For example, if I have two models:
+
+```
+class Order < ActiveRecord::Base
+  has_many :line_items, autosave: true
+end
+
+class LineItem < ActiveRecord::Base
+  belongs_to :order
+end
+```
+
+I can send a resource document to `POST /api/v1/orders` that looks like this:
+
+```json
+{
+  "data": {
+    "type": "orders",
+    "attributes": {
+      "some_order_attribute": "..."
+    },
+    "relationships": {
+      "line_items": {
+        "data": [
+          {
+            "type": "line_items",
+            "attributes": {
+              "price": 5.0
+            }
+          },
+          {
+            "type": "line_items",
+            "attributes": {
+              "price": 6.0
+            }
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+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:
+
+```json
+{
+  "errors": [
+    {
+      "source": { "pointer": "/data/attributes/price" },
+      "code": "blank",
+      "detail": "Price cannot be blank."
+    },
+    {
+      "source": { "pointer": "/data/relationships/line_items" },
+      "code": "blank",
+      "detail": "Line items cannot be blank."
+    },
+    {
+      "source": { "pointer": "/data/relationships/line_items/data/attributes/price" },
+      "code": "blank",
+      "detail": "Price cannot be blank."
+    }
+  ]
+}
+```
+
+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. But using the same user-friendly error message to a third party API developer is kinda weird.
+
+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'`
+
+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]
+
+# for errors on base
+api.v1.errors.models.[model_name].[code]
+api.v1.errors.[code]
+```
+
+#### Controller errors
+
+Controller errors are returned from the server looking like this:
+
+```json
+{
+  "errors": [
+    {
+      "source": { "parameter": "filter" },
+      "code": "invalid",
+      "detail": "Filters provided are invalid."
+    }
+  ]
+}
+```
+
+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:
+
+```
+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
+)
+```
+
+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
+
+# Define URL options for use in UrlHelpers
+config.default_url_options ||= {}
+
+# If true, relationship data will not be serialized unless it is in `include`, huge performance boost
+config.optimize_relationships ||= true
+
+# Defines the translation scope for model and controller errors
+config.i18n_scope ||= '' # 'api.v1.errors'
+
+# The default size of any page queried
+config.default_page_size ||= 10
+
+# The maximum size of any page queried
+config.max_page_size ||= 100
+```
+
+You should also look into the configuration for [ActiveModelSerializers](https://github.com/rails-api/active_model_serializers/blob/master/docs/general/configuration_options.md) to customize the serializer behavior further.
+
+### Overriding an action while still using Caprese helpers
+
+Coming soon... :)
 
 ## Development
 

data/lib/caprese.rb

@@ -18,12 +18,13 @@ module Caprese
   # Define URL options for use in UrlHelpers
   config.default_url_options ||= {}
 
-  # If true, relationship data will not be serialized unless it is in `include`
-  config.optimize_relationships ||= true
-
   # If true, links will be rendered as `only_path: true`
+  # TODO: Implement this
   config.only_path_links ||= true
 
+  # If true, relationship data will not be serialized unless it is in `include`
+  config.optimize_relationships ||= true
+
   # Defines the translation scope for model and controller errors
   config.i18n_scope ||= '' # 'api.v1.errors'
 

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

@@ -81,12 +81,10 @@ module Caprese
     # @note We use the term scope, because the collection may be all records of that type,
     #   or the records may be scoped further by overriding this method
     #
-    # @note If no `type` is provided, the type is assumed to be the controller_record_class
-    #
     # @param [Symbol] type the type to get a record scope for
     # @return [Relation] the scope of records of type `type`
-    def record_scope(type = nil)
-      (type && record_class(type) || controller_record_class).all
+    def record_scope(type)
+      record_class(type).all
     end
 
     # Gets a record in a scope using a column/value to search by
@@ -170,7 +168,7 @@ module Caprese
     # @return [Relation] the record scope of the queried controller
     def queried_record_scope
       unless @queried_record_scope
-        scope = record_scope
+        scope = record_scope(unversion(params[:controller]).to_sym)
 
         if scope.any? && query_params[:filter].try(:any?)
           if (valid_filters = query_params[:filter].select { |k, _| scope.column_names.include? k }).present?

data/lib/caprese/error.rb

@@ -45,8 +45,10 @@ module Caprese
             I18n.t("#{i18n_scope}.models.#{@model}.#{field}.#{code}", t)
           elsif i18n_set?("#{i18n_scope}.field.#{code}", t)
             I18n.t("#{i18n_scope}.field.#{code}", t)
-          else
+          elsif i18n_set? "#{i18n_scope}.#{code}", t
             I18n.t("#{i18n_scope}.#{code}", t)
+          else
+            code.to_s
           end
         else
           if i18n_set? "#{i18n_scope}.models.#{@model}.#{code}", t
@@ -62,8 +64,10 @@ module Caprese
           I18n.t("#{i18n_scope}.controllers.#{@controller}.#{@action}.#{field}.#{code}", t)
         elsif i18n_set?("#{i18n_scope}.controllers.#{@controller}.#{@action}.#{code}", t)
           I18n.t("#{i18n_scope}.controllers.#{@controller}.#{@action}.#{code}", t)
-        else
+        elsif i18n_set? "#{i18n_scope}.#{code}", t
           I18n.t("#{i18n_scope}.#{code}", t)
+        else
+          code.to_s
         end
       elsif field && i18n_set?("#{i18n_scope}.field.#{code}", t)
         I18n.t("#{i18n_scope}.field.#{code}", t)

data/lib/caprese/version.rb

@@ -1,3 +1,3 @@
 module Caprese
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: caprese
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Nick Landgrebe
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-09-21 00:00:00.000000000 Z
+date: 2016-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: active_model_serializers