rest_framework 1.2.0 → 2.0.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8119cab13c69b27ebfa36906e6bcd577688f2ba63b136e0833f4cfdeae3ca5c3
-  data.tar.gz: 149343b13dfdf94b5804beb502d2296d95f487774d1cb3a1dd30dd63f4ab2afc
+  metadata.gz: 639dcc597e17e5148cde3f7511637913be7b431899f59a5cc7f504533969233e
+  data.tar.gz: 0c732ab6c80f9c06b29e4a30e29087ff4fa65206df15b7826ffd9f0d2781b774
 SHA512:
-  metadata.gz: 17d7143b9ac7a9a3f01fab29a369a083750d26f5923bea7d6b9b9dad407efe25bc30321de0024e1d1f3883aa86838bb250b2ee8c4c749e159386b42d5038f5c8
-  data.tar.gz: b1794ca103409bc69f235d72603bd8c9ecd91f674cf4e41c8072ec4c35b4e0d5ca26058f6903554df404183ee7c9624dac9b8f33b67fe212874e98bc4a600355
+  metadata.gz: 656e302db2252a27a30508e1f5c1d2caf2d603288d4ca3e2ec0995355a4a6501b18bc8320463a17113568a562ead98c3896c949a00aa03cc83a6c71f2f62d738
+  data.tar.gz: f760d0140360ca1856dca0ab87b8de1903e09fd7cc442c1b40c9150b7abaf312f43ae67a52a5d0881af9e1f98489a074a82ebaef87b527c99e6e8f7175c67740

data/README.md

@@ -3,7 +3,6 @@
 [![Gem Version](https://badge.fury.io/rb/rest_framework.svg)](https://badge.fury.io/rb/rest_framework)
 [![Pipeline](https://github.com/gregschmit/rails-rest-framework/actions/workflows/pipeline.yml/badge.svg)](https://github.com/gregschmit/rails-rest-framework/actions/workflows/pipeline.yml)
 [![Coverage](https://coveralls.io/repos/github/gregschmit/rails-rest-framework/badge.svg?branch=master)](https://coveralls.io/github/gregschmit/rails-rest-framework?branch=master)
-[![Maintainability](https://api.codeclimate.com/v1/badges/ba5df7706cb544d78555/maintainability)](https://codeclimate.com/github/gregschmit/rails-rest-framework/maintainability)
 
 A framework for DRY RESTful APIs in Ruby on Rails.
 
@@ -44,49 +43,52 @@ To add REST framework features to a controller, include the `Controller` module:
 class ApiController < ApplicationController
   include RESTFramework::Controller
 
-  # Here is where you can set configuration class attributes that will propagate to child
-  # controllers.
-
-  # Setting up a paginator class here makes more sense than defining it on every child controller.
-  self.paginator_class = RESTFramework::PageNumberPaginator
-  self.page_size = 30
+  # Assignments are local by default; wrap shared config in `propagate` so child controllers inherit
+  # it. Settings you want every resource to share belong here rather than on each child controller.
+  propagate do
+    self.page_size = 30
+    self.max_page_size = 100
+  end
 end
 ```
 
+> **Note:** Configuration assignments are **local by default** — `self.x = value` sets `x` on that
+> controller alone and does not propagate to subclasses. To share a setting with every descendant
+> (pagination, filter backends, serializer config, and so on), wrap the assignment in a
+> `propagate` block on a base controller.
+
 Here is what the directory structure might look like for resource controllers:
 
 ```text
 controllers/
 ├─ api_controller.rb
 └─ api/
-   ├─ root_controller.rb
    ├─ movies_controller.rb
    └─ users_controller.rb
 ```
 
-### Root Controller
+### Serving the Root API Index
 
-It is typically a good pattern for the root of your API to have a dedicated `Api::RootController`
-outside the inheritance chain of your other API controllers, so that you can define actions on the
-root without them propagating to child controllers, and so you can set global configuration on the
-`ApiController`.
+A controller without a `model` renders its `index_content` at its index path, which serves as the
+API root. Because declared actions are local by default (they don't propagate to subclasses), you
+can serve the index — and any root-specific extra actions — straight from your API's base
+controller:
 
 ```ruby
-class Api::RootController < ApiController
-  self.extra_actions = {test: :get}
-
-  # The root action is routed by `rest_root`.
-  def root
-    render(
-      api: {
-        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
-      },
-    )
+class ApiController < ApplicationController
+  include RESTFramework::Controller
+
+  add_action(:test, :get)
+
+  # Rendered at the `/api` root. Defaults to the controller's `description`.
+  def index_content
+    {
+      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
@@ -97,14 +99,15 @@ end
 
 ### Resource Controllers
 
-Other API controllers can be associated to a resource/model by setting the `model` class attribute.
+Other API controllers can be associated to a resource/model by setting `model`, e.g.
+`self.model = Movie`.
 
 ```ruby
 class Api::MoviesController < ApiController
   self.model = Movie  # Automatically routes the standard CRUD actions for this controller.
   self.bulk = true  # Enables bulk create/update/destroy actions for this controller.
   self.fields = [:id, :name, :release_date, :enabled]
-  self.extra_member_actions = {first: :get}
+  add_action(:first, :get, type: :member)
 
   def first
     # Always use bang methods, since the framework will rescue `RecordNotFound` and return a
@@ -123,30 +126,29 @@ to include or exclude fields rather than defining them manually:
 
 ```ruby
 class Api::UsersController < ApiController
-  self.fields = {include: [:calculated_popularity], exclude: [:impersonation_token]}
+  # Include a method `popularity` and exclude the `impersonation_token` column.
+  self.fields = {include: [:popularity], exclude: [:impersonation_token]}
 
   # You can even disable some of the builtin actions. For example, this effectively makes the
   # resource read-only:
-  self.excluded_actions = [:create, :update, :destroy, :update_all, :destroy_all]
+  remove_actions(:create, :update, :destroy, :update_all, :destroy_all)
 end
 ```
 
 ### Routing
 
-Use `rest_route` for non-resourceful controllers, or `rest_resource` / `rest_resources` resourceful
-routers. These routers add some features to the Rails builtin `resource`/`resources` routers, such
-as automatically routing extra actions defined on the controller. To route the root, use
-`rest_root`.
+Use `rest_route` to route any controller. It wraps Rails' `resource` / `resources` routers, picking
+`resources` for a plural model controller and `resource` otherwise, and automatically routes the
+controller's built-in and extra actions. A controller with a `model` gets the full CRUD set; a
+modelless controller is routed at its root (its `index`, which renders `index_content`).
 
 ```ruby
 Rails.application.routes.draw do
-  # 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'.
+  rest_route :api  # `ApiController` serves the `/api` root.
 
   namespace :api do
-    rest_root  # Will route `Api::RootController#root` to '/' in this namespace ('/api').
-    rest_resources :movies
-    rest_resources :users
+    rest_route :movies
+    rest_route :users
   end
 end
 ```
@@ -163,3 +165,69 @@ web server and the job queue, which serves the test app and coverage/brakeman re
 - Test App: [http://127.0.0.1:3000](http://127.0.0.1:3000)
 - API: [http://127.0.0.1:3000/api](http://127.0.0.1:3000/api)
 - Reports: [http://127.0.0.1:3000/reports](http://127.0.0.1:3000/reports)
+
+## Version 2
+
+Version 2 is a substantial overhaul. The highlights below cover the major additions and behavior
+changes; the migration checklist that follows walks through updating an existing app.
+
+### New Features & Improvements
+
+- **Simpler setup** — a single `include RESTFramework::Controller` replaces the per-type `*Mixin`
+  modules.
+- **Local-by-default configuration** — assignments stay on the controller they're set on; wrap
+  shared settings in a `propagate` block to hand them down. Config no longer leaks silently onto
+  every resource.
+- **Declarative actions** — `add_action` / `remove_action` declare extra routes with an explicit
+  `member` / `collection` scope and per-declaration propagation, and can disable built-ins too,
+  replacing the `extra_actions` config hashes.
+- **Unified routing** — one `rest_route` (accepting several names) replaces `rest_resource` /
+  `rest_resources` / `rest_root`; a modelless controller serves the API root from its
+  `index_content`.
+- **Action delegation** — mark an action `metadata: { delegate: true }` to dispatch it to a model
+  class method (collection) or record method (member), passing query params through as args/kwargs.
+- **Consumer-driven association queries** (opt-in via `enable_association_queries`) — clients can
+  request extra fields for a serialized association (`?associations.<name>.fields=a,b,c`) and raise
+  its per-request record limit (`?associations.<name>.limit=N` or `all`), both bounded by a
+  per-association allowlist so an association never exposes more than its own endpoint would.
+- **`page_total_count`** — skip the `COUNT` query so pagination stays fast on very large tables.
+
+### Behavior Changes
+
+- **Pagination is on by default** (`PageNumberPaginator`, page size 20), so `index` responses are
+  bounded out of the box; opt out per controller with `paginator_class = nil`.
+- **Ordering and pagination read from the query string only**, never the request body.
+- **A `find_by` on a non-permitted field returns `404`** rather than matching a virtual or
+  serialized field.
+- **Delegated actions wrap their result under a `return` key**, and raise on a missing or non-public
+  target instead of silently 404-ing.
+- **Removed** `rrf_finalize` and the `auto_finalize` / `freeze_config` hooks.
+- **Security hardening** — `find_by`, filtering, ordering, and search are scoped to serialized,
+  non-`write_only` fields (so hidden/secret columns can't be used as lookup/enumeration keys), plus
+  per-element read-only stripping on bulk writes, an ordering-oracle fix, sanitized
+  `StatementInvalid` messages, and safer query-filter parsing.
+
+### Migrating from Older Versions
+
+See the guide for details on each item.
+
+- [ ] Replace the `*Mixin` modules with `include RESTFramework::Controller` on the core API
+      controller.
+- [ ] Set `self.model = ...` on every resource controller (it's no longer inferred from the name).
+- [ ] Wrap inherited config in a `propagate` block — assignments are now local by default.
+- [ ] Convert `extra_actions` / `extra_member_actions` hashes to `add_action` / `remove_action`.
+- [ ] Render custom actions with `render(api: ...)`, replacing the older `api_response(...)` /
+      `render_api(...)`.
+- [ ] Replace `rest_resource` / `rest_resources` / `rest_root` with `rest_route`.
+- [ ] Fold any dedicated root controller into the namespace's base controller, which now serves the
+      root via `index_content` (the standalone `root` action and `rest_root` are gone).
+- [ ] Rename `singleton_controller` → `singular`.
+- [ ] Remove `rrf_finalize` calls and the `auto_finalize` / `freeze_config` config (all gone).
+- [ ] Expect paginated `index` responses by default (`self.paginator_class = nil` restores a bare
+      array).
+- [ ] Rename config: `sub_fields` → `fields`, `native_serializer_associations_limit[_max]` →
+      `association_limit[_max]`, `native_serializer_include_associations_count` →
+      `include_association_count`; the `?associations_limit=N` param is gone.
+- [ ] Note client-visible behavior changes: delegated actions wrap their result under a `return`
+      key; a non-permitted `find_by` returns `404`; `update_all` / `destroy_all` are plural-only;
+      ordering/pagination read from the query string only.

data/VERSION

@@ -1 +1 @@
-1.2.0
+2.0.0.beta2

data/lib/rest_framework/controller/actions.rb

@@ -0,0 +1,256 @@
+module RESTFramework::Controller
+  # Value object describing a routed action (builtin or user-declared).
+  ActionSpec = Struct.new(
+    :name, :type, :methods, :path, :metadata, :builtin, :kwargs, keyword_init: true
+  )
+
+  # Builtin actions keyed by name, each gated by a `condition` so only applicable ones surface in
+  # `actions` / `member_actions`. They route at the base path (`""`) of their scope.
+  RRF_BUILTIN_COLLECTION_ACTIONS = {
+    index: { methods: [ :get ], condition: ->(c) { !c.singular }, kwargs: { as: "" } },
+    create: { methods: [ :post ], condition: ->(c) { c.model } },
+    update_all: {
+      methods: [ :put, :patch ],
+      condition: ->(c) { c.model && c.bulk && !c.singular },
+      kwargs: { anchor: true },
+    },
+    destroy_all: {
+      methods: [ :delete ],
+      condition: ->(c) { c.model && c.bulk && !c.singular },
+      kwargs: { anchor: true },
+    },
+    options: { methods: [ :options ], condition: ->(_c) { true }, kwargs: { anchor: true } },
+  }.freeze
+  RRF_BUILTIN_MEMBER_ACTIONS = {
+    show: { methods: [ :get ], condition: ->(c) { c.model } },
+    update: { methods: [ :put, :patch ], condition: ->(c) { c.model } },
+    destroy: { methods: [ :delete ], condition: ->(c) { c.model } },
+  }.freeze
+
+  module ClassMethods
+    # Per-class action deltas (internal). Public because composition reads them off ancestors.
+    def _rrf_action_adds(type)
+      if type == :member
+        @_rrf_member_action_adds ||= {}
+      else
+        @_rrf_collection_action_adds ||= {}
+      end
+    end
+
+    def _rrf_action_removes(type)
+      if type == :member
+        @_rrf_member_action_removes ||= {}
+      else
+        @_rrf_collection_action_removes ||= {}
+      end
+    end
+
+    # Route an action, choosing the collection/member scope. Pass `type:` on a plural model
+    # controller, where the scopes differ; elsewhere the scope is implied — a singular controller's
+    # sole resource is a member (so `delegate` targets the record), a modelless one has only a
+    # collection — and `type:` warns as unnecessary (unless the action is delegated).
+    def add_action(name, methods, type: nil, **opts)
+      singular_model = self.model && self.singular
+
+      if self.model && !self.singular
+        _rrf_warn_action(name, methods, type, :ambiguous) if type.nil?
+      elsif singular_model && type && !opts[:metadata]&.[](:delegate)
+        _rrf_warn_action(name, methods, type, :redundant)
+      end
+
+      _rrf_add_action(type || (singular_model ? :member : :collection), name, methods, **opts)
+    end
+
+    # Remove an action from routing (including builtins). With no `type:`, both scopes are removed —
+    # keeping removal simple, and letting `propagate:` carry it to model descendants where member
+    # scope matters. Pass `type:` to target a single scope.
+    def remove_action(name, type: nil, propagate: false)
+      if type
+        _rrf_remove_action(type, name, propagate: propagate)
+      else
+        _rrf_remove_action(:collection, name, propagate: propagate)
+        _rrf_remove_action(:member, name, propagate: propagate)
+      end
+    end
+
+    def remove_actions(*names, type: nil, propagate: false)
+      names.each { |name| remove_action(name, type: type, propagate: propagate) }
+    end
+
+    # Source of truth: the effective collection / member actions (builtins + declared, composed
+    # across the inheritance chain), as an ordered `Hash{Symbol => ActionSpec}`.
+    def actions
+      _rrf_compose_actions(:collection)
+    end
+
+    def member_actions
+      _rrf_compose_actions(:member)
+    end
+
+    private
+
+    def _rrf_add_action(type, name, methods, path: nil, metadata: nil, propagate: false, **kwargs)
+      name = name.to_sym
+      spec = ActionSpec.new(
+        name: name,
+        type: type,
+        methods: Array(methods).map(&:to_sym),
+        path: (path || name).to_s,
+        metadata: metadata,
+        builtin: false,
+        kwargs: kwargs,
+      )
+      _rrf_action_removes(type).delete(name)
+      _rrf_action_adds(type)[name] = { spec: spec, propagate: _rrf_normalize_propagate(propagate) }
+    end
+
+    def _rrf_remove_action(type, name, propagate: false)
+      name = name.to_sym
+      _rrf_action_adds(type).delete(name)
+      _rrf_action_removes(type)[name] = { propagate: _rrf_normalize_propagate(propagate) }
+    end
+
+    # Normalize `propagate:` to `false` (local), `true` (self + descendants), or `:exclude_self`
+    # (descendants only). Non-standard values warn: `nil` becomes `false`, anything else truthy
+    # becomes `true`.
+    def _rrf_normalize_propagate(value)
+      case value
+      when false
+        false
+      when true, :exclude_self
+        value
+      when nil
+        Rails.logger.warn("RRF: `propagate: nil` is nonstandard; treating as `false`.")
+        false
+      else
+        Rails.logger.warn("RRF: invalid `propagate:` value #{value.inspect}; treating as `true`.")
+        true
+      end
+    end
+
+    # Whether an entry with the given `propagate`, declared on some class, reaches the controller
+    # we're composing for. `is_self` is true when that class is the controller itself.
+    def _rrf_reaches?(propagate, is_self)
+      case propagate
+      when :exclude_self
+        !is_self
+      when true
+        true
+      else # false
+        is_self
+      end
+    end
+
+    def _rrf_builtins(type)
+      type == :member ? RRF_BUILTIN_MEMBER_ACTIONS : RRF_BUILTIN_COLLECTION_ACTIONS
+    end
+
+    def _rrf_compose_actions(type)
+      effective = {}
+
+      # 1. Seed with the builtins whose condition holds for this controller.
+      _rrf_builtins(type).each do |name, cfg|
+        next unless cfg[:condition].call(self)
+
+        effective[name] = ActionSpec.new(
+          name: name,
+          type: type,
+          methods: cfg[:methods],
+          path: "",
+          metadata: nil,
+          builtin: true,
+          kwargs: cfg[:kwargs] || {},
+        )
+      end
+
+      # 2. Walk RRF ancestors from farthest to nearest (ending at self), applying each class's
+      #    removes then adds that reach us. Removes-before-adds lets a subclass re-add something an
+      #    ancestor removed; later (nearer) classes win.
+      _rrf_action_chain.each do |klass|
+        is_self = klass.equal?(self)
+
+        klass._rrf_action_removes(type).each do |name, remove|
+          effective.delete(name) if _rrf_reaches?(remove[:propagate], is_self)
+        end
+
+        klass._rrf_action_adds(type).each do |name, add|
+          effective[name] = add[:spec] if _rrf_reaches?(add[:propagate], is_self)
+        end
+      end
+
+      effective
+    end
+
+    def _rrf_action_chain
+      self.ancestors.select { |a| a.is_a?(Class) && a.respond_to?(:_rrf_action_adds) }.reverse
+    end
+
+    # Build the `type:` warning for `add_action`, echoing the call so its source is easy to find.
+    def _rrf_warn_action(name, methods, type, reason)
+      type_arg = type ? ", type: #{type.inspect}" : ""
+      sig = "add_action(#{name.inspect}, #{methods.inspect}#{type_arg})"
+
+      detail =
+        if reason == :ambiguous
+          "needs an explicit `type:` (`:collection` or `:member`); collection and member route " \
+            "differently on a plural model controller"
+        else
+          "has an unnecessary `type:`; member and collection route the same path on a singular " \
+            "model controller"
+        end
+
+      Rails.logger.warn("RRF: `#{sig}` #{detail}.")
+    end
+  end
+
+  # Delegated actions (`metadata: { delegate: true }`) dispatch through `rrf_delegate` while keeping
+  # their declared name for routing and introspection. The route marks itself delegated with the
+  # `rrf_delegate_scope` path parameter, so dispatch is route-based and never collides with a
+  # same-named method.
+  def method_for_action(action_name)
+    request&.path_parameters&.key?(:rrf_delegate_scope) ? "rrf_delegate" : super
+  end
+
+  # Dispatch a delegated action to the model class (collection) or the record (member). Its declared
+  # name is `action_name`; its scope comes from the route.
+  def rrf_delegate
+    target = self.action_name.to_sym
+    member = request.path_parameters[:rrf_delegate_scope].to_s == "member"
+    receiver = member ? self.get_record : self.class.model
+
+    # Delegation targets must be public methods. Anything else — a private/protected method, or a
+    # name that resolves to nothing — is developer misconfiguration (a typo, a missing method, or a
+    # method that should be public), so raise loudly rather than dispatch or mask it as a 404.
+    unless receiver.respond_to?(target)
+      raise RESTFramework::DelegatedMethodError.new(receiver, target)
+    end
+
+    parameters = receiver.method(target).parameters
+    query = request.query_parameters
+
+    # Positional arguments come from the reserved `args` param: a scalar becomes a single
+    # positional, an array is splatted as all of them.
+    args = query.key?("args") ? Array.wrap(query["args"]) : []
+
+    # Remaining query params splat as kwargs only when the method accepts arbitrary keywords
+    # (`**opts`); scan all params so a trailing block (`&blk`) doesn't hide the `:keyrest`.
+    kwargs = if parameters.any? { |type, _| type == :keyrest }
+      query.except("args").symbolize_keys
+    else
+      {}
+    end
+
+    result = receiver.public_send(target, *args, **kwargs)
+
+    # Serialize Active Record return values through the framework serializer (honoring field
+    # exclusions); `render_api` only does this for top-level payloads, and we nest under `return`.
+    if result.is_a?(ActiveRecord::Base) || result.is_a?(ActiveRecord::Relation)
+      result = self.serialize(result)
+    end
+
+    # Wrap the result under a `return` key rather than rendering it at the top level: the method may
+    # return `nil` (which `render_api` rejects) or a bare scalar/array that isn't a good serializer
+    # root, and this leaves room to attach metadata alongside it later.
+    render_api({ return: result })
+  end
+end

data/lib/rest_framework/controller/bulk.rb

@@ -95,12 +95,12 @@ module RESTFramework::Controller
   def create_all
     if self._bulk_mode == :raw
       result = self.create_all_raw!
-      return render(api: { message: "Bulk create successful.", result: result })
+      return render_api({ message: "Bulk create successful.", result: result })
     end
 
     records = self.create_all_default!
-    render(
-      api: { message: "Bulk create successful.", records: self._bulk_serialize(records) },
+    render_api(
+      { message: "Bulk create successful.", records: self._bulk_serialize(records) },
       status: :created,
     )
   end
@@ -146,18 +146,20 @@ module RESTFramework::Controller
   def update_all
     if self._bulk_mode == :raw
       result = self.update_all_raw!
-      return render(api: { message: "Bulk update successful.", result: result })
+      return render_api({ message: "Bulk update successful.", result: result })
     end
 
     records = self.update_all_default!
-    render(api: { message: "Bulk update successful.", records: self._bulk_serialize(records) })
+    render_api({ message: "Bulk update successful.", records: self._bulk_serialize(records) })
   end
 
   def update_all_raw!
     pk = self.class.model.primary_key
+    pk_type = self.class.model.type_for_attribute(pk)
     data = self._bulk_object_data(:update, :raw)
 
-    data_ids = data.map { |r| r[pk] }.uniq
+    # Cast ids like `update_all_default!` so the existence check compares matching types.
+    data_ids = data.map { |r| pk_type.cast(r[pk]) }.uniq
     if data_ids.include?(nil)
       raise RESTFramework::InvalidBulkParametersError.new(
         "Bulk update requires the primary key (#{pk}) for all records.",
@@ -183,9 +185,12 @@ module RESTFramework::Controller
 
   def update_all_default!
     pk = self.class.model.primary_key
+    pk_type = self.class.model.type_for_attribute(pk)
     data = self._bulk_object_data(:update, :default)
 
-    data_ids = data.map { |r| r[pk] }.uniq
+    # Cast ids to the pk's type so they match records fetched from the DB; JSON clients often send
+    # ids as strings, which otherwise never match the type-cast keys of `existing` below.
+    data_ids = data.map { |r| pk_type.cast(r[pk]) }.uniq
     if data_ids.include?(nil)
       raise RESTFramework::InvalidBulkParametersError.new(
         "Bulk update requires the primary key (#{pk}) for all records.",
@@ -201,7 +206,7 @@ module RESTFramework::Controller
 
     # Assign attributes to each record.
     records = data.map { |attrs|
-      record = existing[attrs[pk]]
+      record = existing[pk_type.cast(attrs[pk])]
       record.assign_attributes(attrs.except(pk))
       record
     }
@@ -229,11 +234,11 @@ module RESTFramework::Controller
   def destroy_all
     if self._bulk_mode == :raw
       deleted = self.destroy_all_raw!
-      return render(api: { message: "Bulk destroy successful.", result: deleted })
+      return render_api({ message: "Bulk destroy successful.", result: deleted })
     end
 
     records = self.destroy_all_default!
-    render(api: { message: "Bulk destroy successful.", records: self._bulk_serialize(records) })
+    render_api({ message: "Bulk destroy successful.", records: self._bulk_serialize(records) })
   end
 
   def destroy_all_raw!

data/lib/rest_framework/controller/crud.rb

@@ -5,7 +5,7 @@ module RESTFramework::Controller
       return self.create_all
     end
 
-    render(api: self.create!, status: :created)
+    render_api(self.create!, status: :created)
   end
 
   # Perform the `create!` call and return the created record.
@@ -14,7 +14,7 @@ module RESTFramework::Controller
   end
 
   def index
-    render(api: self.index!)
+    render_api(self.class.model ? self.index! : self.index_content)
   end
 
   # Get records with both filtering and pagination applied.
@@ -38,12 +38,17 @@ module RESTFramework::Controller
     records
   end
 
+  # The payload rendered at a non-model controller's index (e.g. an API root). Override this.
+  def index_content
+    { message: self.class.description.presence || "This is the API root." }
+  end
+
   def show
-    render(api: self.get_record)
+    render_api(self.get_record)
   end
 
   def update
-    render(api: self.update!)
+    render_api(self.update!)
   end
 
   # Perform the `update!` call and return the updated record.
@@ -55,7 +60,7 @@ module RESTFramework::Controller
 
   def destroy
     self.destroy!
-    render(api: "")
+    render_api("")
   end
 
   # Perform the `destroy!` call and return the destroyed (and frozen) record.

data/lib/rest_framework/controller/openapi.rb

@@ -180,6 +180,7 @@ module RESTFramework::Controller
           end
 
           v[:readOnly] = true if cfg[:read_only]
+          v[:writeOnly] = true if cfg[:write_only]
           v[:default] = cfg[:default] if cfg.key?(:default)
 
           if enum_variants = cfg[:enum_variants]
@@ -206,8 +207,8 @@ module RESTFramework::Controller
               join_table: ref.respond_to?(:join_table) ? ref.join_table : nil,
             }.compact
             v[:"x-rrf-association_pk"] = cfg[:association_pk]
-            v[:"x-rrf-sub_fields"] = cfg[:sub_fields]
-            v[:"x-rrf-sub_fields_metadata"] = cfg[:sub_fields_metadata]
+            v[:"x-rrf-association_fields"] = cfg[:fields]
+            v[:"x-rrf-association_fields_metadata"] = cfg[:association_fields_metadata]
             v[:"x-rrf-id_field"] = cfg[:id_field]
             v[:"x-rrf-nested_attributes_options"] = cfg[:nested_attributes_options]
           end