rest_framework 0.9.8 → 0.9.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b06a61592498f8debce6f504b4eee90ceeef6fdff63dbb769bd70c623cd9631
-  data.tar.gz: ab5b1284a3504104b77cc38278bad01a1dfa30ce7ebcd65323b73e0dd31e58a2
+  metadata.gz: 4b816fbe24e240ce66a74b2a3c18fd0a75a449c878c9a0126e4c14ddbaafe5b8
+  data.tar.gz: 383836204fd789afd4270794e0d7da57e05b8b8e8f537dd19c7fa2bf6ff1e2eb
 SHA512:
-  metadata.gz: ed04505314f252ac1058732a875711090fb07499edac42814bf72e5b15f90f833040e40399df279654727041af30789c8a931e06d83b9fc1c67f46d4f0da850f
-  data.tar.gz: abd68ae8ab71f2fff8f7a933270a467811143096f7cdde16d21c99ac3faeadc8f958cb0bcdde94c1b57f1d620fc278f8d9b5e3b4e2cec5851fb4616f9c325d41
+  metadata.gz: 0a845ce1b30eab8ad874e432268092e5e9117200a320d9446a3e333a88d202257987767fd6b9bad2b7b0768c52e564e1a0beede15408027c7c48c8b91beffcd4
+  data.tar.gz: a1ae6ccfd603c7759d5db717249790a7b124bc06b39ff3f88eba16527874ec8788e4fdcb149c4e96ca0a6a8dae1ea3361519acfb830e1dfda6bc5ea2b521177b

data/README.md

@@ -27,87 +27,122 @@ YARD Docs: [rubydoc.info/gems/rest_framework](https://rubydoc.info/gems/rest_fra
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'rest_framework'
+gem "rest_framework"
 ```
 
-And then execute:
+And then run:
 
 ```shell
-$ bundle install
+bundle install
 ```
 
-Or install it yourself with:
+## Quick Usage Tutorial
 
-```shell
-$ gem install rest_framework
-```
+This section provides some simple examples to quickly get you started using the framework.
 
-## Quick Usage Tutorial
+For the purpose of this example, you'll want to add an `api_controller.rb` to your controllers, as
+well as a directory for the resources:
+
+```text
+controllers/
+├─ api_controller.rb
+└─ api/
+   ├─ root_controller.rb
+   ├─ movies_controller.rb
+   └─ users_controller.rb
+```
 
 ### Controller Mixins
 
-To transform a controller into a RESTful controller, you can either include `BaseControllerMixin`,
-`ReadOnlyModelControllerMixin`, or `ModelControllerMixin`. `BaseControllerMixin` provides a `root`
-action and a simple interface for routing arbitrary additional actions:
+The root `ApiController` can include any common behavior you want to share across all your API
+controllers:
 
 ```ruby
 class ApiController < ApplicationController
   include RESTFramework::BaseControllerMixin
+
+  # Setting up a paginator class here makes more sense than defining it on every child controller.
+  self.paginator_class = RESTFramework::PageNumberPaginator
+
+  # The page_size attribute doesn't exist on the `BaseControllerMixin`, but for child controllers
+  # that include the `ModelControllerMixin`, they will inherit this attribute and will not overwrite
+  # it.
+  class_attribute(:page_size, default: 30)
+end
+```
+
+A root controller can provide actions that exist on the root of your API. It's best to define a
+dedicated root controller, rather than using the `ApiController` for this purpose, so that actions
+don't propagate to child controllers:
+
+```ruby
+class Api::RootController < ApiController
   self.extra_actions = {test: :get}
 
+  def root
+    return api_response(
+      {
+        message: "Welcome to the API.",
+        how_to_authenticate: <<~END.lines.map(&:strip).join(" "),
+          You can use this API with your normal login session. Otherwise, you can insert your API
+          key into a Bearer Authorization header, or into the URL parameters with the name
+          `api_key`.
+        END
+      },
+    )
+  end
+
   def test
-    render api_response({message: "Test successful!"})
+    return api_response({message: "Hello, world!"})
   end
 end
 ```
 
-`ModelControllerMixin` assists with providing the standard model CRUD for your controller.
+And here is an example of a resource controller:
 
 ```ruby
 class Api::MoviesController < ApiController
   include RESTFramework::ModelControllerMixin
 
-  self.recordset = Movie.where(enabled: true)
+  self.fields = [:id, :name, :release_date, :enabled]
+  self.extra_member_actions = {first: :get}
+
+  def first
+    # Always use the bang method, since the framework will rescue `RecordNotFound` and return a
+    # sensible error response.
+    return api_response(self.get_records.first!)
+  end
+
+  def get_recordset
+    return Movie.where(enabled: true)
+  end
 end
 ```
 
-`ReadOnlyModelControllerMixin` only enables list/show actions, but since we're naming this
-controller in a way that doesn't make the model obvious, we can set that explicitly:
+You can also configure a resource's fields dynamically using `include` and `exclude` keys:
 
 ```ruby
-class Api::ReadOnlyMoviesController < ApiController
-  include RESTFramework::ReadOnlyModelControllerMixin
+class Api::UsersController < ApiController
+  include RESTFramework::ModelControllerMixin
 
-  self.model = Movie
+  self.fields = {include: [:calculated_popularity], exclude: [:impersonation_token]}
 end
 ```
 
-Note that you can also override the `get_recordset` instance method to override the API behavior
-dynamically per-request.
-
 ### Routing
 
 You can use Rails' `resource`/`resources` routers to route your API, however if you want
 `extra_actions` / `extra_member_actions` to be routed automatically, then you can use `rest_route`
-for non-resourceful controllers, or `rest_resource` / `rest_resources` resourceful routers. You can
-also use `rest_root` to route the root of your API:
+for non-resourceful controllers, or `rest_resource` / `rest_resources` resourceful routers. To route
+the root, use `rest_root`.
 
 ```ruby
 Rails.application.routes.draw do
-  rest_root :api  # will find `api_controller` and route the `root` action to '/api'
-  namespace :api do
-    rest_resources :movies
-    rest_resources :users
-  end
-end
-```
-
-Or if you want the API root to be routed to `Api::RootController#root`:
+  # If you wanted to route actions from the `ApiController`, then you would use this:
+  # rest_root :api  # Will find `api_controller` and route the `root` action to '/api'.
 
-```ruby
-Rails.application.routes.draw do
   namespace :api do
-    rest_root  # will route `Api::RootController#root` to '/' in this namespace ('/api')
+    rest_root  # Will route `Api::RootController#root` to '/' in this namespace ('/api').
     rest_resources :movies
     rest_resources :users
   end
@@ -117,14 +152,7 @@ end
 ## Development/Testing
 
 After you clone the repository, cd'ing into the directory should create a new gemset if you are
-using RVM. Then run `bundle install` to install the appropriate gems.
-
-To run the test suite:
-
-```shell
-$ rails test
-```
+using RVM. Then run `bin/setup` to install the appropriate gems and set things up.
 
 The top-level `bin/rails` proxies all Rails commands to the test project, so you can operate it via
-the usual commands. Ensure you run `rails db:setup` before running `rails server` or
-`rails console`.
+the usual commands (e.g., `rails test`, `rails server` and `rails console`).

data/VERSION

@@ -1 +1 @@
-0.9.8
+0.9.9

data/app/views/rest_framework/_head.html.erb

@@ -29,7 +29,6 @@
   h1, h2, h3, h4, h5, h6 {
     color: var(--rrf-red);
     font-weight: normal;
-    margin-bottom: 0;
   }
   html[data-bs-theme="dark"] h1,
   html[data-bs-theme="dark"] h2,
@@ -290,7 +289,7 @@
 
   // Convert plain-text links to anchor tag links.
   function rrfLinkify(text) {
-    return text.replace(/(https?:\/\/[^\s<>"]+)/g, "<a href=\"$1\" target=\"_blank\">$1</a>")
+    return text.replace(/(https?:\/\/[^\s<>"]+)/g, "<a href=\"$1\">$1</a>")
   }
 
   // Replace the document when doing form submission (mainly to support PUT/PATCH/DELETE).

data/app/views/rest_framework/_heading.html.erb

@@ -1,7 +1,7 @@
 <div class="row">
   <div>
     <%= render partial: "rest_framework/heading/actions" if @route_groups.present? %>
-    <h1 class="m-0"><%= @heading_title || @title %></h1>
+    <h1 style="margin: 0"><%= @heading_title || @title %></h1>
     <% if @description.present? %>
       <br><br><p style="display: inline-block; margin-bottom: 0"><%= @description %></p>
     <% end %>

data/app/views/rest_framework/_payloads.html.erb

@@ -17,7 +17,7 @@
       <% end %>
     </ul>
   </div>
-  <div class="tab-content pt-2">
+  <div class="tab-content">
     <div class="tab-pane fade show active" id="tab-json" role="tabpanel">
       <% if @json_payload.present? %>
         <div><pre class="rrf-copy"><code class="language-json"><%=

data/app/views/rest_framework/_request_metadata.html.erb

@@ -1,16 +1,14 @@
 <div class="row">
   <div>
-    <pre><code><%
+    <pre class="mb-2"><code class="language-plaintext"><%
       concat request.request_method
       if request.method != request.request_method
         concat " (via #{request.method})"
       end
       concat " #{request.path}"
     %></code></pre>
-    <pre><code><%
+    <pre><code class="language-plaintext"><%
       concat "HTTP #{response.status} #{response.message}"
-      concat "\n"
-      concat "Content-Type: #{response.content_type}"
     %></code></pre>
   </div>
 </div>

data/app/views/rest_framework/_routes_and_forms.html.erb

@@ -34,7 +34,7 @@
       <% end %>
     </ul>
   </div>
-  <div class="tab-content pt-2">
+  <div class="tab-content">
     <div class="tab-pane fade show active" id="tab-routes" role="tabpanel">
       <%= render partial: "rest_framework/routes_and_forms/routes" %>
     </div>
@@ -49,4 +49,4 @@
       </div>
     <% end %>
   </div>
-</div>
+</div>

data/lib/rest_framework/errors/base_error.rb

@@ -0,0 +1,5 @@
+class RESTFramework::Errors::BaseError < StandardError
+end
+
+# Alias for convenience.
+RESTFramework::BaseError = RESTFramework::Errors::BaseError

data/lib/rest_framework/errors/nil_passed_to_api_response_error.rb

@@ -0,0 +1,14 @@
+class RESTFramework::Errors::NilPassedToAPIResponseError < RESTFramework::Errors::BaseError
+  def message
+    return <<~MSG.split("\n").join(" ")
+      Payload of `nil` was passed to `api_response`; this is unsupported. If you want a blank
+      response, pass `''` (an empty string) as the payload. If this was the result of a `find_by`
+      (or similar Active Record method) not finding a record, you should use the bang version (e.g.,
+      `find_by!`) to raise `ActiveRecord::RecordNotFound`, which the REST controller will catch and
+      return an appropriate error response.
+    MSG
+  end
+end
+
+# Alias for convenience.
+RESTFramework::NilPassedToAPIResponseError = RESTFramework::Errors::NilPassedToAPIResponseError

data/lib/rest_framework/errors/unknown_model_error.rb

@@ -0,0 +1,18 @@
+class RESTFramework::Errors::UnknownModelError < RESTFramework::Errors::BaseError
+  def initialize(controller_class)
+    super()
+    @controller_class = controller_class
+  end
+
+  def message
+    return <<~MSG.split("\n").join(" ")
+      The model class for `#{@controller_class}` could not be determined. Any controller that
+      includes `RESTFramework::BaseModelControllerMixin` (directly or indirectly) must either set
+      the `model` attribute on the controller, or the model must be deducible from the controller
+      name (e.g., `UsersController` could resolve to the `User` model).
+    MSG
+  end
+end
+
+# Alias for convenience.
+RESTFramework::UnknownModelError = RESTFramework::Errors::UnknownModelError

data/lib/rest_framework/errors.rb

@@ -1,31 +1,7 @@
-# Top-level class for all REST Framework errors.
-class RESTFramework::Error < StandardError
+module RESTFramework::Errors
 end
 
-class RESTFramework::NilPassedToAPIResponseError < RESTFramework::Error
-  def message
-    return <<~MSG.split("\n").join(" ")
-      Payload of `nil` was passed to `api_response`; this is unsupported. If you want a blank
-      response, pass `''` (an empty string) as the payload. If this was the result of a `find_by`
-      (or similar Active Record method) not finding a record, you should use the bang version (e.g.,
-      `find_by!`) to raise `ActiveRecord::RecordNotFound`, which the REST controller will catch and
-      return an appropriate error response.
-    MSG
-  end
-end
-
-class RESTFramework::UnknownModelError < RESTFramework::Error
-  def initialize(controller_class)
-    super()
-    @controller_class = controller_class
-  end
+require_relative "errors/base_error"
 
-  def message
-    return <<~MSG.split("\n").join(" ")
-      The model class for `#{@controller_class}` could not be determined. Any controller that
-      includes `RESTFramework::BaseModelControllerMixin` (directly or indirectly) must either set
-      the `model` attribute on the controller, or the model must be deducible from the controller
-      name (e.g., `UsersController` could resolve to the `User` model).
-    MSG
-  end
-end
+require_relative "errors/nil_passed_to_api_response_error"
+require_relative "errors/unknown_model_error"

data/lib/rest_framework/mixins/bulk_model_controller_mixin.rb

@@ -31,9 +31,6 @@ module RESTFramework::Mixins::BulkCreateModelMixin
   end
 end
 
-# Alias for convenience.
-RESTFramework::BulkCreateModelMixin = RESTFramework::Mixins::BulkCreateModelMixin
-
 # Mixin for updating records in bulk.
 module RESTFramework::Mixins::BulkUpdateModelMixin
   def update_all
@@ -59,9 +56,6 @@ module RESTFramework::Mixins::BulkUpdateModelMixin
   end
 end
 
-# Alias for convenience.
-RESTFramework::BulkUpdateModelMixin = RESTFramework::Mixins::BulkUpdateModelMixin
-
 # Mixin for destroying records in bulk.
 module RESTFramework::Mixins::BulkDestroyModelMixin
   def destroy_all
@@ -89,21 +83,21 @@ module RESTFramework::Mixins::BulkDestroyModelMixin
   end
 end
 
-# Alias for convenience.
-RESTFramework::BulkDestroyModelMixin = RESTFramework::Mixins::BulkDestroyModelMixin
-
 # Mixin that includes all the CRUD bulk mixins.
 module RESTFramework::Mixins::BulkModelControllerMixin
-  include RESTFramework::ModelControllerMixin
+  include RESTFramework::Mixins::ModelControllerMixin
 
-  include RESTFramework::BulkCreateModelMixin
-  include RESTFramework::BulkUpdateModelMixin
-  include RESTFramework::BulkDestroyModelMixin
+  include RESTFramework::Mixins::BulkCreateModelMixin
+  include RESTFramework::Mixins::BulkUpdateModelMixin
+  include RESTFramework::Mixins::BulkDestroyModelMixin
 
   def self.included(base)
-    RESTFramework::ModelControllerMixin.included(base)
+    RESTFramework::Mixins::ModelControllerMixin.included(base)
   end
 end
 
-# Alias for convenience.
+# Aliases for convenience.
+RESTFramework::BulkCreateModelMixin = RESTFramework::Mixins::BulkCreateModelMixin
+RESTFramework::BulkUpdateModelMixin = RESTFramework::Mixins::BulkUpdateModelMixin
+RESTFramework::BulkDestroyModelMixin = RESTFramework::Mixins::BulkDestroyModelMixin
 RESTFramework::BulkModelControllerMixin = RESTFramework::Mixins::BulkModelControllerMixin

data/lib/rest_framework/mixins/model_controller_mixin.rb

@@ -631,9 +631,6 @@ module RESTFramework::Mixins::BaseModelControllerMixin
   end
 end
 
-# Alias for convenience.
-RESTFramework::BaseModelControllerMixin = RESTFramework::Mixins::BaseModelControllerMixin
-
 # Mixin for listing records.
 module RESTFramework::Mixins::ListModelMixin
   def index
@@ -662,9 +659,6 @@ module RESTFramework::Mixins::ListModelMixin
   end
 end
 
-# Alias for convenience.
-RESTFramework::ListModelMixin = RESTFramework::Mixins::ListModelMixin
-
 # Mixin for showing records.
 module RESTFramework::Mixins::ShowModelMixin
   def show
@@ -672,9 +666,6 @@ module RESTFramework::Mixins::ShowModelMixin
   end
 end
 
-# Alias for convenience.
-RESTFramework::ShowModelMixin = RESTFramework::Mixins::ShowModelMixin
-
 # Mixin for creating records.
 module RESTFramework::Mixins::CreateModelMixin
   def create
@@ -687,9 +678,6 @@ module RESTFramework::Mixins::CreateModelMixin
   end
 end
 
-# Alias for convenience.
-RESTFramework::CreateModelMixin = RESTFramework::Mixins::CreateModelMixin
-
 # Mixin for updating records.
 module RESTFramework::Mixins::UpdateModelMixin
   def update
@@ -704,9 +692,6 @@ module RESTFramework::Mixins::UpdateModelMixin
   end
 end
 
-# Alias for convenience.
-RESTFramework::UpdateModelMixin = RESTFramework::Mixins::UpdateModelMixin
-
 # Mixin for destroying records.
 module RESTFramework::Mixins::DestroyModelMixin
   def destroy
@@ -720,38 +705,39 @@ module RESTFramework::Mixins::DestroyModelMixin
   end
 end
 
-# Alias for convenience.
-RESTFramework::DestroyModelMixin = RESTFramework::Mixins::DestroyModelMixin
-
 # Mixin that includes show/list mixins.
 module RESTFramework::Mixins::ReadOnlyModelControllerMixin
-  include RESTFramework::BaseModelControllerMixin
+  include RESTFramework::Mixins::BaseModelControllerMixin
 
-  include RESTFramework::ListModelMixin
-  include RESTFramework::ShowModelMixin
+  include RESTFramework::Mixins::ListModelMixin
+  include RESTFramework::Mixins::ShowModelMixin
 
   def self.included(base)
     RESTFramework::BaseModelControllerMixin.included(base)
   end
 end
 
-# Alias for convenience.
-RESTFramework::ReadOnlyModelControllerMixin = RESTFramework::Mixins::ReadOnlyModelControllerMixin
-
 # Mixin that includes all the CRUD mixins.
 module RESTFramework::Mixins::ModelControllerMixin
-  include RESTFramework::BaseModelControllerMixin
+  include RESTFramework::Mixins::BaseModelControllerMixin
 
-  include RESTFramework::ListModelMixin
-  include RESTFramework::ShowModelMixin
-  include RESTFramework::CreateModelMixin
-  include RESTFramework::UpdateModelMixin
-  include RESTFramework::DestroyModelMixin
+  include RESTFramework::Mixins::ListModelMixin
+  include RESTFramework::Mixins::ShowModelMixin
+  include RESTFramework::Mixins::CreateModelMixin
+  include RESTFramework::Mixins::UpdateModelMixin
+  include RESTFramework::Mixins::DestroyModelMixin
 
   def self.included(base)
     RESTFramework::BaseModelControllerMixin.included(base)
   end
 end
 
-# Alias for convenience.
+# Aliases for convenience.
+RESTFramework::BaseModelControllerMixin = RESTFramework::Mixins::BaseModelControllerMixin
+RESTFramework::ListModelMixin = RESTFramework::Mixins::ListModelMixin
+RESTFramework::ShowModelMixin = RESTFramework::Mixins::ShowModelMixin
+RESTFramework::CreateModelMixin = RESTFramework::Mixins::CreateModelMixin
+RESTFramework::UpdateModelMixin = RESTFramework::Mixins::UpdateModelMixin
+RESTFramework::DestroyModelMixin = RESTFramework::Mixins::DestroyModelMixin
+RESTFramework::ReadOnlyModelControllerMixin = RESTFramework::Mixins::ReadOnlyModelControllerMixin
 RESTFramework::ModelControllerMixin = RESTFramework::Mixins::ModelControllerMixin

data/lib/rest_framework/paginators/page_number_paginator.rb

@@ -59,13 +59,24 @@ class RESTFramework::Paginators::PageNumberPaginator < RESTFramework::Paginators
 
   # Wrap the serialized page with appropriate metadata. TODO: include links.
   def get_paginated_response(serialized_page)
+    page_query_param = @controller.page_query_param
+    base_params = @controller.params.to_unsafe_h
+    next_url = if @page_number < @total_pages
+      @controller.url_for({**base_params, page_query_param => @page_number + 1})
+    end
+    previous_url = if @page_number > 1
+      @controller.url_for({**base_params, page_query_param => @page_number - 1})
+    end
+
     return {
       count: @count,
       page: @page_number,
       page_size: @page_size,
       total_pages: @total_pages,
+      next: next_url,
+      previous: previous_url,
       results: serialized_page,
-    }
+    }.compact
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rest_framework
 version: !ruby/object:Gem::Version
-  version: 0.9.8
+  version: 0.9.9
 platform: ruby
 authors:
 - Gregory N. Schmit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-07-07 00:00:00.000000000 Z
+date: 2023-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -53,6 +53,9 @@ files:
 - lib/rest_framework.rb
 - lib/rest_framework/engine.rb
 - lib/rest_framework/errors.rb
+- lib/rest_framework/errors/base_error.rb
+- lib/rest_framework/errors/nil_passed_to_api_response_error.rb
+- lib/rest_framework/errors/unknown_model_error.rb
 - lib/rest_framework/filters.rb
 - lib/rest_framework/filters/base_filter.rb
 - lib/rest_framework/filters/model_ordering_filter.rb