rest_framework 0.8.16 → 0.8.17

data/docs/Gemfile.lock

@@ -0,0 +1,264 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (7.0.4.3)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+    addressable (2.8.2)
+      public_suffix (>= 2.0.2, < 6.0)
+    coffee-script (2.4.1)
+      coffee-script-source
+      execjs
+    coffee-script-source (1.11.1)
+    colorator (1.1.0)
+    commonmarker (0.23.8)
+    concurrent-ruby (1.2.2)
+    dnsruby (1.61.9)
+      simpleidn (~> 0.1)
+    em-websocket (0.5.3)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0)
+    ethon (0.16.0)
+      ffi (>= 1.15.0)
+    eventmachine (1.2.7)
+    execjs (2.8.1)
+    faraday (2.7.4)
+      faraday-net_http (>= 2.0, < 3.1)
+      ruby2_keywords (>= 0.0.4)
+    faraday-net_http (3.0.2)
+    ffi (1.15.5)
+    forwardable-extended (2.6.0)
+    gemoji (3.0.1)
+    github-pages (228)
+      github-pages-health-check (= 1.17.9)
+      jekyll (= 3.9.3)
+      jekyll-avatar (= 0.7.0)
+      jekyll-coffeescript (= 1.1.1)
+      jekyll-commonmark-ghpages (= 0.4.0)
+      jekyll-default-layout (= 0.1.4)
+      jekyll-feed (= 0.15.1)
+      jekyll-gist (= 1.5.0)
+      jekyll-github-metadata (= 2.13.0)
+      jekyll-include-cache (= 0.2.1)
+      jekyll-mentions (= 1.6.0)
+      jekyll-optional-front-matter (= 0.3.2)
+      jekyll-paginate (= 1.1.0)
+      jekyll-readme-index (= 0.3.0)
+      jekyll-redirect-from (= 0.16.0)
+      jekyll-relative-links (= 0.6.1)
+      jekyll-remote-theme (= 0.4.3)
+      jekyll-sass-converter (= 1.5.2)
+      jekyll-seo-tag (= 2.8.0)
+      jekyll-sitemap (= 1.4.0)
+      jekyll-swiss (= 1.0.0)
+      jekyll-theme-architect (= 0.2.0)
+      jekyll-theme-cayman (= 0.2.0)
+      jekyll-theme-dinky (= 0.2.0)
+      jekyll-theme-hacker (= 0.2.0)
+      jekyll-theme-leap-day (= 0.2.0)
+      jekyll-theme-merlot (= 0.2.0)
+      jekyll-theme-midnight (= 0.2.0)
+      jekyll-theme-minimal (= 0.2.0)
+      jekyll-theme-modernist (= 0.2.0)
+      jekyll-theme-primer (= 0.6.0)
+      jekyll-theme-slate (= 0.2.0)
+      jekyll-theme-tactile (= 0.2.0)
+      jekyll-theme-time-machine (= 0.2.0)
+      jekyll-titles-from-headings (= 0.5.3)
+      jemoji (= 0.12.0)
+      kramdown (= 2.3.2)
+      kramdown-parser-gfm (= 1.1.0)
+      liquid (= 4.0.4)
+      mercenary (~> 0.3)
+      minima (= 2.5.1)
+      nokogiri (>= 1.13.6, < 2.0)
+      rouge (= 3.26.0)
+      terminal-table (~> 1.4)
+    github-pages-health-check (1.17.9)
+      addressable (~> 2.3)
+      dnsruby (~> 1.60)
+      octokit (~> 4.0)
+      public_suffix (>= 3.0, < 5.0)
+      typhoeus (~> 1.3)
+    html-pipeline (2.14.3)
+      activesupport (>= 2)
+      nokogiri (>= 1.4)
+    http_parser.rb (0.8.0)
+    i18n (1.12.0)
+      concurrent-ruby (~> 1.0)
+    jekyll (3.9.3)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (>= 0.7, < 2)
+      jekyll-sass-converter (~> 1.0)
+      jekyll-watch (~> 2.0)
+      kramdown (>= 1.17, < 3)
+      liquid (~> 4.0)
+      mercenary (~> 0.3.3)
+      pathutil (~> 0.9)
+      rouge (>= 1.7, < 4)
+      safe_yaml (~> 1.0)
+    jekyll-avatar (0.7.0)
+      jekyll (>= 3.0, < 5.0)
+    jekyll-coffeescript (1.1.1)
+      coffee-script (~> 2.2)
+      coffee-script-source (~> 1.11.1)
+    jekyll-commonmark (1.4.0)
+      commonmarker (~> 0.22)
+    jekyll-commonmark-ghpages (0.4.0)
+      commonmarker (~> 0.23.7)
+      jekyll (~> 3.9.0)
+      jekyll-commonmark (~> 1.4.0)
+      rouge (>= 2.0, < 5.0)
+    jekyll-default-layout (0.1.4)
+      jekyll (~> 3.0)
+    jekyll-feed (0.15.1)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-gist (1.5.0)
+      octokit (~> 4.2)
+    jekyll-github-metadata (2.13.0)
+      jekyll (>= 3.4, < 5.0)
+      octokit (~> 4.0, != 4.4.0)
+    jekyll-include-cache (0.2.1)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-mentions (1.6.0)
+      html-pipeline (~> 2.3)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-optional-front-matter (0.3.2)
+      jekyll (>= 3.0, < 5.0)
+    jekyll-paginate (1.1.0)
+    jekyll-readme-index (0.3.0)
+      jekyll (>= 3.0, < 5.0)
+    jekyll-redirect-from (0.16.0)
+      jekyll (>= 3.3, < 5.0)
+    jekyll-relative-links (0.6.1)
+      jekyll (>= 3.3, < 5.0)
+    jekyll-remote-theme (0.4.3)
+      addressable (~> 2.0)
+      jekyll (>= 3.5, < 5.0)
+      jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0)
+      rubyzip (>= 1.3.0, < 3.0)
+    jekyll-sass-converter (1.5.2)
+      sass (~> 3.4)
+    jekyll-seo-tag (2.8.0)
+      jekyll (>= 3.8, < 5.0)
+    jekyll-sitemap (1.4.0)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-swiss (1.0.0)
+    jekyll-theme-architect (0.2.0)
+      jekyll (> 3.5, < 5.0)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-cayman (0.2.0)
+      jekyll (> 3.5, < 5.0)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-dinky (0.2.0)
+      jekyll (> 3.5, < 5.0)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-hacker (0.2.0)
+      jekyll (> 3.5, < 5.0)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-leap-day (0.2.0)
+      jekyll (> 3.5, < 5.0)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-merlot (0.2.0)
+      jekyll (> 3.5, < 5.0)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-midnight (0.2.0)
+      jekyll (> 3.5, < 5.0)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-minimal (0.2.0)
+      jekyll (> 3.5, < 5.0)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-modernist (0.2.0)
+      jekyll (> 3.5, < 5.0)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-primer (0.6.0)
+      jekyll (> 3.5, < 5.0)
+      jekyll-github-metadata (~> 2.9)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-slate (0.2.0)
+      jekyll (> 3.5, < 5.0)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-tactile (0.2.0)
+      jekyll (> 3.5, < 5.0)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-time-machine (0.2.0)
+      jekyll (> 3.5, < 5.0)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-titles-from-headings (0.5.3)
+      jekyll (>= 3.3, < 5.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    jemoji (0.12.0)
+      gemoji (~> 3.0)
+      html-pipeline (~> 2.2)
+      jekyll (>= 3.0, < 5.0)
+    kramdown (2.3.2)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    liquid (4.0.4)
+    listen (3.8.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    mercenary (0.3.6)
+    mini_portile2 (2.8.1)
+    minima (2.5.1)
+      jekyll (>= 3.5, < 5.0)
+      jekyll-feed (~> 0.9)
+      jekyll-seo-tag (~> 2.1)
+    minitest (5.18.0)
+    nokogiri (1.14.2)
+      mini_portile2 (~> 2.8.0)
+      racc (~> 1.4)
+    octokit (4.25.1)
+      faraday (>= 1, < 3)
+      sawyer (~> 0.9)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    public_suffix (4.0.7)
+    racc (1.6.2)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rexml (3.2.5)
+    rouge (3.26.0)
+    ruby2_keywords (0.0.5)
+    rubyzip (2.3.2)
+    safe_yaml (1.0.5)
+    sass (3.7.4)
+      sass-listen (~> 4.0.0)
+    sass-listen (4.0.0)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+    sawyer (0.9.2)
+      addressable (>= 2.3.5)
+      faraday (>= 0.17.3, < 3)
+    simpleidn (0.2.1)
+      unf (~> 0.1.4)
+    terminal-table (1.8.0)
+      unicode-display_width (~> 1.1, >= 1.1.1)
+    typhoeus (1.4.0)
+      ethon (>= 0.9.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unf (0.1.4)
+      unf_ext
+    unf_ext (0.0.8.2)
+    unicode-display_width (1.8.0)
+    webrick (1.7.0)
+    yard (0.9.28)
+      webrick (~> 1.7.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  github-pages
+  yard
+
+BUNDLED WITH
+   2.2.33

data/docs/_config.yml

@@ -0,0 +1,17 @@
+title: Rails REST Framework
+email: schmitgreg@gmail.com
+description: Rails REST Framework helps you build awesome Web APIs in Ruby on Rails.
+url: "https://rails-rest-framework.com"
+collections:
+  guide:
+    output: true
+    permalink: /:collection/:slug/
+
+# Build settings
+markdown: kramdown
+
+defaults:
+  - scope:
+      path: ""  # All files.
+    values:
+      layout: default

data/docs/_guide/1_routers.md

@@ -0,0 +1,110 @@
+---
+layout: default
+title: Routers
+position: 1
+slug: routers
+---
+# Routers
+
+You can route RESTful controllers with the normal utilities that Rails provides. However, the REST
+framework also provides some helpers to route controllers using attributes of the controllers
+themselves.
+
+## Routing the API Root
+
+Your API root should probably have some content describing how one can authenticate with the API,
+and what sub-controllers exist in the API. The API root can also be a great place to put singleton
+actions on your API, if needed.
+
+There are two common ways for an API root to be implemented.
+
+### Inherited API Root
+
+You likely have an API controller that your other controllers inherit from, like this:
+
+```shell
+app/controllers/
+├── api
+│   ├── groups_controller.rb
+│   ├── movies_controller.rb
+│   ├── marbles_controller.rb
+│   └── users_controller.rb
+├── api_controller.rb
+└── application_controller.rb
+```
+
+If your controllers in the `api` directory inherit from `ApiController` and you want root actions on
+`ApiController`, then you would setup your root route in the top-level namespace, like this:
+
+```ruby
+Rails.application.routes.draw do
+  rest_root :api
+  namespace :api do
+    ...
+  end
+end
+```
+
+However, note that actions defined on `ApiController` are defined on all sub-controllers, so if
+you're using `match` rules to route controllers, then this may lead to undesired behavior.
+
+### Dedicated API Root
+
+A better way might be to dedicate a controller for the API root, which would prevent actions and
+properties defined on the root API from propagating to the rest of the namespace through
+inheritance. You would add a `RootController` so your directory would look like this:
+
+```shell
+app/controllers/
+├── api
+│   ├── groups_controller.rb
+│   ├── movies_controller.rb
+│   ├── root_controller.rb
+│   ├── marbles_controller.rb
+│   └── users_controller.rb
+├── api_controller.rb
+└── application_controller.rb
+```
+
+Now you can route the root in the `:api` namespace, like this:
+
+```ruby
+Rails.application.routes.draw do
+  namespace :api do
+    rest_root  # By default this will find and route `Api::RootController`.
+    ...
+  end
+end
+```
+
+## Resourceful Routing
+
+The REST Framework provides resourceful routers `rest_resource` and `rest_resources`, analogous to
+Rails' `resource` and `resources`. These routers will inspect their corresponding controllers and
+route `extra_actions` (aliased with `extra_collection_actions`) and `extra_member_actions`
+automatically.
+
+```ruby
+Rails.application.routes.draw do
+  namespace :api do
+    rest_root
+    rest_resource :user
+    rest_resources :movies
+  end
+end
+```
+
+## Non-resourceful Routing
+
+The `rest_route` non-resourceful router does not route the standard resource routes (`index`,
+`create`, `show`, `list`, `update`, `delete`). Any actions must be defined as `extra_actions` on the
+controller.
+
+```ruby
+Rails.application.routes.draw do
+  namespace :api do
+    rest_root
+    rest_route :network
+  end
+end
+```

data/docs/_guide/2_controller_mixins.md

@@ -0,0 +1,293 @@
+---
+layout: default
+title: Controller Mixins
+position: 2
+slug: controller-mixins
+---
+# Controller Mixins
+
+This is the core of the REST Framework. Generally speaking, projects already have an existing
+controller inheritance hierarchy, so we want developers to be able to maintain that project
+structure while leveraging the power of the REST Framework. Also, different controllers which
+inherit from the same parent often need different REST Framework mixins. For these reasons, REST
+Framework provides the controller functionality as modules that you mix into your controllers.
+
+## Response Rendering
+
+Before we go into the various controller mixins, one of the core capabilities of the REST Framework
+is to provide system-consumable responses along side a browsable API for developers. While you can
+use Rails' builtin rendering tools, such as `render`, the REST Framework provides a rendering helper
+called `api_response`. This helper allows you to return a browsable API response for the `html`
+format which shows you what the JSON/XML response would look like, along with faster and lighter
+responses for `json` and `xml` formats.
+
+Here is an example:
+
+```ruby
+class ApiController < ApplicationController
+  include RESTFramework::BaseControllerMixin
+  self.extra_actions = {test: :get}
+
+  def test
+    api_response({message: "Test successful!"})
+  end
+end
+```
+
+## `BaseControllerMixin`
+
+To transform a controller into the simplest possible RESTful controller, you can include
+`BaseControllerMixin`, which provides a simple `root` action so it can be used at the API root.
+
+```ruby
+class ApiController < ApplicationController
+  include RESTFramework::BaseControllerMixin
+end
+```
+
+### Controller Attributes
+
+You can customize the behavior of `BaseControllerMixin` by setting or mutating various class
+attributes.
+
+#### `singleton_controller`
+
+This property primarily controls the routes that are generated for a RESTful controller. If you use
+`api_resource`/`api_resources` to define whether the generates routes are for a collection or for
+a single member, then you do not need to use this property. However, if you are autogenerating those
+routers, then `singleton_controller` will tell REST Framework whether to provide collection routes
+(when `singleton_controller` is falsy) or member routes (when `singleton_controller` is truthy). To
+read more about singular vs plural routing, see Rails' documentation here:
+https://guides.rubyonrails.org/routing.html#singular-resources.
+
+#### `extra_actions`
+
+This property defines extra actions on the controller to be routed. It is a hash of
+`endpoint -> method(s)` (where `method(s)` can be a method symbol or an array of method symbols).
+
+```ruby
+class ApiController < ApplicationController
+  include RESTFramework::BaseControllerMixin
+  self.extra_actions = {test: :get}
+
+  def test
+    api_response({message: "Test successful!"})
+  end
+end
+```
+
+Or with multiple methods:
+
+```ruby
+class ApiController < ApplicationController
+  include RESTFramework::BaseControllerMixin
+  self.extra_actions = {test: [:get, :post]}
+
+  def test
+    api_response({message: "Test successful!"})
+  end
+end
+```
+
+If your action conflicts with a builtin method, then you can also override the path:
+
+```ruby
+class ApiController < ApplicationController
+  include RESTFramework::BaseControllerMixin
+
+  # This will route `test_action` to `/test`, in case there is already a `test` method that cannot
+  # be overridden.
+  self.extra_actions = {test_action: {path: :test, methods: :get}}
+
+  def test_action
+    api_response({message: "Test successful!"})
+  end
+end
+```
+
+## `ModelControllerMixin`
+
+`ModelControllerMixin` assists with providing the standard model CRUD (create, read, update,
+destroy) for your controller. This is the most commonly used mixin since it provides default
+behavior for models which matches Rails' default routing.
+
+```ruby
+class Api::MoviesController < ApiController
+  include RESTFramework::ModelControllerMixin
+end
+```
+
+By default, all columns and associations are included in `self.fields`, which can be helpful when
+developing an administrative API. For user-facing APIs, however, `self.fields` should always be
+explicitly defined.
+
+### Controller Attributes
+
+You can customize the behavior of `ModelControllerMixin` by setting or mutating various class
+attributes.
+
+#### `model`
+
+The `model` property allows you to define the model if it is not obvious from the controller name.
+
+```ruby
+class Api::CoolMoviesController < ApiController
+  include RESTFramework::ModelControllerMixin
+
+  self.model = Movie
+end
+```
+
+#### `recordset`
+
+The `recordset` property allows you to define the set of records this API should be limited to. If
+you need to change the recordset based on properties of the request, then you can override the
+`get_recordset()` method.
+
+```ruby
+class Api::CoolMoviesController < ApiController
+  include RESTFramework::ModelControllerMixin
+
+  self.recordset = Movie.where(cool: true).order({id: :asc})
+end
+```
+
+#### `extra_member_actions`
+
+The `extra_member_actions` property allows you to define additional actions on individual records.
+
+```ruby
+class Api::MoviesController < ApiController
+  include RESTFramework::ModelControllerMixin
+
+  self.extra_member_actions = {disable: :post}
+
+  def disable
+    @record = self.get_record  # REST Framework will rescue ActiveRecord::RecordNotFound
+
+    # REST Framework will rescue ActiveRecord::RecordInvalid or ActiveRecord::RecordNotSaved
+    @record.update!(enabled: false)
+
+    return api_response(@record)
+  end
+end
+```
+
+#### `fields`
+
+The `fields` property defines the default fields for serialization and for parameters allowed from
+the body or query string.
+
+```ruby
+class Api::MoviesController < ApiController
+  include RESTFramework::ModelControllerMixin
+
+  self.fields = [:id, :name]
+end
+```
+
+#### `action_fields`
+
+The `action_fields` property is similar to `fields`, but allows you to define different fields for
+different actions. A good example is to serialize expensive computed properties only in the `show`
+action, but not in the `list` action (where many records are serialized).
+
+```ruby
+class Api::MoviesController < ApiController
+  include RESTFramework::ModelControllerMixin
+
+  self.fields = [:id, :name]
+  self.action_fields = {
+    show: [:id, :name, :some_expensive_computed_property],
+  }
+end
+```
+
+#### `native_serializer_config`
+
+These properties define the serializer configuration if you are using the native `ActiveModel`
+serializer. You can also specify serializers for singular/plural
+
+```ruby
+class Api::MoviesController < ApiController
+  include RESTFramework::ModelControllerMixin
+
+  self.native_serializer_config = {
+    only: [:id, :name],
+    methods: [:active, :some_expensive_computed_property],
+    include: {cast_members: { only: [:id, :name], methods: [:net_worth] }},
+  }
+
+  # Or you could configure a default and a plural serializer:
+  self.native_serializer_plural_config = {
+    only: [:id, :name],
+    methods: [:active],
+    include: {cast_members: { only: [:id, :name], methods: [:net_worth] }},
+  }
+  self.native_serializer_config = {
+    only: [:id, :name],
+    methods: [:active, :some_expensive_computed_property],
+    include: {cast_members: { only: [:id, :name], methods: [:net_worth] }},
+  }
+
+  # Or you could configure a default and a singular serializer:
+  self.native_serializer_config = {
+    only: [:id, :name],
+    methods: [:active],
+    include: {cast_members: { only: [:id, :name], methods: [:net_worth] }},
+  }
+  self.native_serializer_singular_config = {
+    only: [:id, :name],
+    methods: [:active, :some_expensive_computed_property],
+    include: {cast_members: { only: [:id, :name], methods: [:net_worth] }},
+  }
+end
+```
+
+#### `allowed_parameters` / `allowed_action_parameters`
+
+These properties define the permitted parameters to be used in the request body for create/update
+actions. If you need different allowed parameters, then you can also override the
+`get_create_params` or `get_update_params` methods.
+
+```ruby
+class Api::MoviesController < ApiController
+  include RESTFramework::ModelControllerMixin
+
+  self.allowed_parameters = [:name]
+end
+```
+
+#### `create_from_recordset` (default: `true`)
+
+The `create_from_recordset` attribute (`true` by default) is a boolean to control the behavior in
+the `create` action. If it is disabled, records will not be created from the filtered recordset, but
+rather will be created directly from the model interface.
+
+For example, if this is your controller:
+
+```ruby
+class Api::CoolMoviesController < ApiController
+  include RESTFramework::ModelControllerMixin
+
+  def get_recordset
+    return Movie.where(cool: true)
+  end
+end
+```
+
+Then if you hit the `create` action with the payload `{name: "Superman"}`, it will also set `cool`
+to `true` on the new record, because that property is inherited from the recordset.
+
+## `ReadOnlyModelControllerMixin`
+
+`ReadOnlyModelControllerMixin` only enables list/show actions. In this example, since we're naming
+this controller in a way that doesn't make the model obvious, we can set that explicitly:
+
+```ruby
+class Api::ReadOnlyMoviesController < ApiController
+  include RESTFramework::ReadOnlyModelControllerMixin
+
+  self.model = Movie
+end
+```