Merge pull request #2778 from ruby-grape/endpoint_api_kwarg

Rename Grape::Endpoint's for: keyword to api: and expose #api

Author: dblock

CHANGELOG.md

@@ -7,6 +7,7 @@
 * [#2775](https://github.com/ruby-grape/grape/pull/2775): Pass `http_methods` to `Grape::Endpoint` as a keyword instead of via options - [@ericproulx](https://github.com/ericproulx).
 * [#2776](https://github.com/ruby-grape/grape/pull/2776): Pass `path` to `Grape::Endpoint` as a keyword instead of via options - [@ericproulx](https://github.com/ericproulx).
 * [#2777](https://github.com/ruby-grape/grape/pull/2777): Add `Grape::Endpoint#mounted_app` reader and `app:` keyword - [@ericproulx](https://github.com/ericproulx).
+* [#2778](https://github.com/ruby-grape/grape/pull/2778): Rename `Grape::Endpoint`'s `for:` keyword to `api:` and expose `#api` - [@ericproulx](https://github.com/ericproulx).
 * Your contribution here.
 
 #### Fixes

UPGRADING.md

@@ -23,6 +23,20 @@ Grape::Endpoint.new(settings, http_methods: :get, path: '/foo', for: self)
 
 Relatedly, an endpoint's public `options` Hash no longer carries `:method` or `:path`. Nothing in Grape read `:method`, and the only reader of `:path` was an internal test; both values are available from the route instead — `route.request_method` for the verb and `route.path` for the (compiled) path, which is what grape-swagger and other introspection already use. The raw definition-time path array is no longer exposed on the endpoint.
 
+#### `Grape::Endpoint.new` takes `api:` instead of `for:`
+
+The keyword identifying the API an endpoint belongs to has been renamed from `for:` — a reserved word whose value can't be referenced as a local — to `api:`:
+
+```ruby
+# before
+Grape::Endpoint.new(settings, http_methods: :get, path: '/foo', for: my_api)
+
+# after
+Grape::Endpoint.new(settings, http_methods: :get, path: '/foo', api: my_api)
+```
+
+The owning API is no longer carried on the endpoint's public `options` Hash — `endpoint.options[:for]` is gone. Use the new `endpoint.api` reader instead.
+
 ### Upgrading to >= 3.3
 
 #### Minimum required Ruby is now 3.3

lib/grape/dsl/inside_route.rb

@@ -15,7 +15,7 @@ def version
       end
 
       def configuration
-        config.for.configuration.evaluate
+        config.api.configuration.evaluate
       end
 
       # End the request and display an error to the

lib/grape/dsl/routing.rb

@@ -160,7 +160,7 @@ def mount(mounts, *opts)
             path:,
             app:,
             route_options: { anchor: false },
-            for: self
+            api: self
           )
         end
       end
@@ -189,7 +189,7 @@ def route(methods, paths = ['/'], route_options = {}, &)
           inheritable_setting,
           http_methods:,
           path: paths,
-          for: self,
+          api: self,
           route_options: all_route_options,
           &
         )

lib/grape/endpoint.rb

@@ -17,12 +17,13 @@ class Endpoint
     def_delegators :request, :params, :headers, :cookies
     def_delegator :cookies, :response_cookies
 
+    # The API (a +Grape::API+ instance) this endpoint belongs to.
+    def_delegator :@config, :api
+
     # The logger configured on the API this endpoint belongs to. Available
     # inside route handlers, +before+/+after+/+after_validation+/+finally+
     # filters, and +rescue_from+ blocks.
-    def logger
-      config.for.logger
-    end
+    def_delegator :api, :logger
 
     # The Rack app or Grape API mounted at this endpoint, or +nil+ for a plain
     # block endpoint. Prefer this over +options[:app]+, which is retained only
@@ -49,6 +50,8 @@ def block_to_unbound_method(block)
     #   reach this endpoint.
     # @param path [String or Array] the path to this endpoint, within the
     #   current scope.
+    # @param api [Grape::API] the API this endpoint belongs to. Exposed as
+    #   {#api}.
     # @param app [#call, nil] the Rack app or Grape API mounted at this
     #   endpoint; +nil+ for a plain block endpoint. Exposed as {#mounted_app}.
     # @param options [Hash] attributes of this endpoint, normalized into a
@@ -57,7 +60,7 @@ def block_to_unbound_method(block)
     # @note This happens at the time of API definition, so in this context the
     # endpoint does not know if it will be mounted under a different endpoint.
     # @yield a block defining what your API should do when this endpoint is hit
-    def initialize(new_settings, http_methods:, path:, app: nil, **options, &block)
+    def initialize(new_settings, http_methods:, path:, api:, app: nil, **options, &block)
       self.inheritable_setting = new_settings.point_in_time_copy
 
       # now +namespace_stackable(:declared_params)+ contains all params defined for
@@ -70,7 +73,7 @@ def initialize(new_settings, http_methods:, path:, app: nil, **options, &block)
       inheritable_setting.namespace_inheritable[:default_error_status] ||= 500
 
       @options = options
-      @config = Options.new(http_methods:, path:, app:, **options)
+      @config = Options.new(http_methods:, path:, api:, app:, **options)
       # +:app+ is still surfaced on the public options Hash for backwards
       # compatibility (e.g. grape-swagger); prefer the +mounted_app+ reader.
       @options[:app] = app if app

lib/grape/endpoint/options.rb

@@ -6,8 +6,8 @@ class Endpoint
     # +Grape::Endpoint.new+. Internal to {Grape::Endpoint}, which builds it
     # from the +**options+ Hash in #initialize so the public +options+ reader
     # stays a plain Hash for downstream gems (e.g. grape-swagger).
-    Options = Data.define(:path, :http_methods, :for, :route_options, :app, :format) do
-      def initialize(path:, http_methods:, route_options: {}, app: nil, format: nil, **rest)
+    Options = Data.define(:path, :http_methods, :api, :route_options, :app, :format) do
+      def initialize(path:, http_methods:, api:, route_options: {}, app: nil, format: nil)
         path = Array(path)
         path << '/' if path.empty?
         http_methods = Array(http_methods)

spec/grape/dsl/routing_spec.rb

@@ -157,7 +157,7 @@ class << self
       expect(Grape::Endpoint).to receive(:new) do |_inheritable_setting, endpoint_options|
         expect(endpoint_options[:http_methods]).to eq :get
         expect(endpoint_options[:path]).to eq '/foo'
-        expect(endpoint_options[:for]).to eq subject
+        expect(endpoint_options[:api]).to eq subject
         expect(endpoint_options[:route_options]).to eq(foo: 'bar', fiz: 'baz', params: { nuz: 'naz' })
       end.and_yield
 

spec/grape/endpoint_spec.rb

@@ -1034,7 +1034,7 @@ def memoized
         path: '/path',
         app: {},
         route_options: { anchor: false },
-        for: Class.new
+        api: Class.new
       }
     end
     let(:settings) { Grape::Util::InheritableSetting.new }

spec/grape/named_api_spec.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 describe Grape::API do
-  subject(:api_name) { NamedAPI.endpoints.last.options[:for].to_s }
+  subject(:api_name) { NamedAPI.endpoints.last.api.to_s }
 
   let(:api) do
     Class.new(Grape::API) do