rest_framework 0.8.16 → 0.9.0

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
+```

data/docs/_guide/3_serializers.md

@@ -0,0 +1,60 @@
+---
+layout: default
+title: Serializers
+position: 3
+slug: serializers
+---
+# Serializers
+
+Serializers allow complex objects to be converted to Ruby primitives (`Array` and `Hash` objects),
+which can then be converted to JSON or XML.
+
+## NativeSerializer
+
+This serializer uses Rails' native `ActiveModel::Serializers.serializable_hash` method to convert
+records/recordsets to Ruby primitives (`Array` and `Hash`).
+
+This is the default serializer, you can configure it using the controller class attributes
+`native_serializer_config` (or `native_serializer_singular_config` /
+`native_serializer_plural_config`):
+
+```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] }},
+  }
+end
+```
+
+If you want to re-use a serializer, then you can define it as a standalone class, and you can even
+nest them. You can also define separate configurations for serializing individual records vs
+recordsets using `singular_config` and `plural_config`, respectively.
+
+```ruby
+class Api::MoviesController < ApiController
+  include RESTFramework::ModelControllerMixin
+
+  class CastMemberSerializer < RESTFramework::NativeSerializer
+    self.config = { only: [:id, :name], methods: [:net_worth] }
+    self.plural_config = { only: [:id, :name] }
+  end
+
+  class MovieSerializer < RESTFramework::NativeSerializer
+    self.config = {
+      only: [:id, :name],
+      include: {cast_members: CastMemberSerializer.new(many: true)},
+    }
+    self.singular_config = {
+      only: [:id, :name],
+      methods: [:active, :some_expensive_computed_property],
+      include: {cast_members: CastMemberSerializer.new(many: true)},
+    }
+  end
+
+  self.serializer_class = MovieSerializer
+end
+```

data/docs/_guide/4_filtering_and_ordering.md

@@ -0,0 +1,41 @@
+---
+layout: default
+title: Filtering / Ordering
+position: 4
+slug: filtering-and-ordering
+---
+# Filtering and Ordering
+
+While you can control the recordset that the API exposes, sometimes you want the user to control the
+records they want to see, or the order of those records. Both filtering and ordering are
+accomplished through what we call filters. To control the filter backends that a controller uses,
+you can either adjust the `filter_backends` controller attribute or you can override the
+`get_filter_backends()` method.
+
+## `ModelFilter`
+
+This filter provides basic user-controllable filtering of the recordset using query params. For
+example, a request to `/api/movies?cool=true` could return movies where `cool` is `true`.
+
+If you include `ModelControllerMixin` into your controller, `ModelFilter` is included in the filter
+backends by default.
+
+## `ModelOrderingFilter`
+
+This filter provides basic user-controllable ordering of the recordset using query params. For
+example, a request to `/api/movies?ordering=name` could order the movies by `name` rather than `id`.
+`ordering=-name` would invert the ordering. You can also order with multiple parameters with a comma
+separated list, like: `ordering=director,-name`.
+
+If you include `ModelControllerMixin` into your controller, `ModelOrderingFilter` is included in the
+filter backends by default. You can use `ordering_fields` to controller which fields are allowed to
+be ordered by. To adjust the parameter that the user passes, adjust `ordering_query_param`; the
+default is `"ordering"`.
+
+## `ModelSearchFilter`
+
+This filter provides basic user-controllable searching of the recordset using the `search` query
+parameter (adjustable with the `search_query_param`). For example, a request to
+`/api/movies?search=Star` could return movies where `name` contains the string `Star`. The search is
+performed against the `search_fields` attribute, but if that is not set, then the search is
+performed against a configurable default set of fields (`search_columns`).

data/docs/_guide/5_pagination.md

@@ -0,0 +1,21 @@
+---
+layout: default
+title: Pagination
+position: 5
+slug: pagination
+---
+# Pagination
+
+For large result sets, you may need to provide pagination. You can configure the paginator for a
+controller by setting the `paginator_class` to the paginator you want to use.
+
+## PageNumberPaginator
+
+This is a simple paginator which splits a recordset into pages and allows the user to select the
+desired page using the `page` query parameter (e.g., `/api/movies?page=3`). To adjust this query
+parameter, set the `page_query_param` controller attribute.
+
+By default the user can adjust the page size using the `page_size` query param. To adjust this query
+parameter, you can set the `page_size_query_param` controller attribute, or set it to `nil` to
+disable this functionality. By default, there is no upper limit to the size of a page a user can
+request. To enforce an upper limit, set the `max_page_size` controller attribute.

data/docs/_includes/anchor_headings.html

@@ -0,0 +1,144 @@
+{% capture headingsWorkspace %}
+  {% comment %}
+    Copyright (c) 2018 Vladimir "allejo" Jimenez
+
+    Permission is hereby granted, free of charge, to any person
+    obtaining a copy of this software and associated documentation
+    files (the "Software"), to deal in the Software without
+    restriction, including without limitation the rights to use,
+    copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following
+    conditions:
+
+    The above copyright notice and this permission notice shall be
+    included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+    OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+    HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+    WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+    OTHER DEALINGS IN THE SOFTWARE.
+  {% endcomment %}
+  {% comment %}
+    Version 1.0.7
+      https://github.com/allejo/jekyll-anchor-headings
+
+    "Be the pull request you wish to see in the world." ~Ben Balter
+
+    Usage:
+      {% include anchor_headings.html html=content anchorBody="#" %}
+
+    Parameters:
+      * html          (string) - the HTML of compiled markdown generated by kramdown in Jekyll
+
+    Optional Parameters:
+      * beforeHeading (bool)   : false  - Set to true if the anchor should be placed _before_ the heading's content
+      * anchorAttrs   (string) :  ''    - Any custom HTML attributes that will be added to the `<a>` tag; you may NOT use `href`, `class` or `title`;
+                                          the `%heading%` and `%html_id%` placeholders are available
+      * anchorBody    (string) :  ''    - The content that will be placed inside the anchor; the `%heading%` placeholder is available
+      * anchorClass   (string) :  ''    - The class(es) that will be used for each anchor. Separate multiple classes with a space
+      * anchorTitle   (string) :  ''    - The `title` attribute that will be used for anchors
+      * h_min         (int)    :  1     - The minimum header level to build an anchor for; any header lower than this value will be ignored
+      * h_max         (int)    :  6     - The maximum header level to build an anchor for; any header greater than this value will be ignored
+      * bodyPrefix    (string) :  ''    - Anything that should be inserted inside of the heading tag _before_ its anchor and content
+      * bodySuffix    (string) :  ''    - Anything that should be inserted inside of the heading tag _after_ its anchor and content
+
+    Output:
+      The original HTML with the addition of anchors inside of all of the h1-h6 headings.
+  {% endcomment %}
+
+  {% assign minHeader = include.h_min | default: 1 %}
+  {% assign maxHeader = include.h_max | default: 6 %}
+  {% assign beforeHeading = include.beforeHeading %}
+  {% assign nodes = include.html | split: '<h' %}
+
+  {% capture edited_headings %}{% endcapture %}
+
+  {% for _node in nodes %}
+    {% capture node %}{{ _node | strip }}{% endcapture %}
+
+    {% if node == "" %}
+      {% continue %}
+    {% endif %}
+
+    {% assign nextChar = node | replace: '"', '' | strip | slice: 0, 1 %}
+    {% assign headerLevel = nextChar | times: 1 %}
+
+    <!-- If the level is cast to 0, it means it's not a h1-h6 tag, so let's see if we need to fix it -->
+    {% if headerLevel == 0 %}
+      <!-- Split up the node based on closing angle brackets and get the first one. -->
+      {% assign firstChunk = node | split: '>' | first %}
+
+      <!-- If the first chunk does NOT contain a '<', that means we've broken another HTML tag that starts with 'h' -->
+      {% unless firstChunk contains '<' %}
+        {% capture node %}<h{{ node }}{% endcapture %}
+      {% endunless %}
+
+      {% capture edited_headings %}{{ edited_headings }}{{ node }}{% endcapture %}
+      {% continue %}
+    {% endif %}
+
+    {% capture _closingTag %}</h{{ headerLevel }}>{% endcapture %}
+    {% assign _workspace = node | split: _closingTag %}
+    {% assign _idWorkspace = _workspace[0] | split: 'id="' %}
+    {% assign _idWorkspace = _idWorkspace[1] | split: '"' %}
+    {% assign html_id = _idWorkspace[0] %}
+
+    {% capture _hAttrToStrip %}{{ _workspace[0] | split: '>' | first }}>{% endcapture %}
+    {% assign header = _workspace[0] | replace: _hAttrToStrip, '' %}
+
+    <!-- Build the anchor to inject for our heading -->
+    {% capture anchor %}{% endcapture %}
+
+    {% if html_id and headerLevel >= minHeader and headerLevel <= maxHeader %}
+      {% capture anchor %}href="#{{ html_id }}"{% endcapture %}
+
+      {% if include.anchorClass %}
+        {% capture anchor %}{{ anchor }} class="{{ include.anchorClass }}"{% endcapture %}
+      {% endif %}
+
+      {% if include.anchorTitle %}
+        {% capture anchor %}{{ anchor }} title="{{ include.anchorTitle | replace: '%heading%', header }}"{% endcapture %}
+      {% endif %}
+
+      {% if include.anchorAttrs %}
+        {% capture anchor %}{{ anchor }} {{ include.anchorAttrs | replace: '%heading%', header | replace: '%html_id%', html_id }}{% endcapture %}
+      {% endif %}
+
+      {% capture anchor %}<a {{ anchor }}>{{ include.anchorBody | replace: '%heading%', header | default: '' }}</a>{% endcapture %}
+
+      <!-- In order to prevent adding extra space after a heading, we'll let the 'anchor' value contain it -->
+      {% if beforeHeading %}
+        {% capture anchor %}{{ anchor }} {% endcapture %}
+      {% else %}
+        {% capture anchor %} {{ anchor }}{% endcapture %}
+      {% endif %}
+    {% endif %}
+
+    {% capture new_heading %}
+      <h{{ _hAttrToStrip }}
+        {{ include.bodyPrefix }}
+        {% if beforeHeading %}
+          {{ anchor }}{{ header }}
+        {% else %}
+          {{ header }}{{ anchor }}
+        {% endif %}
+        {{ include.bodySuffix }}
+      </h{{ headerLevel }}>
+    {% endcapture %}
+
+    <!--
+    If we have content after the `</hX>` tag, then we'll want to append that here so we don't lost any content.
+    -->
+    {% assign chunkCount = _workspace | size %}
+    {% if chunkCount > 1 %}
+      {% capture new_heading %}{{ new_heading }}{{ _workspace | last }}{% endcapture %}
+    {% endif %}
+
+    {% capture edited_headings %}{{ edited_headings }}{{ new_heading }}{% endcapture %}
+  {% endfor %}
+{% endcapture %}{% assign headingsWorkspace = '' %}{{ edited_headings | strip }}