easy-peasy-api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5863a5ef0b82d5420acdf6a93d9a085bce84b0b4c3ce72b389e1a2f3460ae5c9
+  data.tar.gz: d645b973b0dd6d79f366361a9cb52a1089981c275dafa540396b2a9308d44f34
+SHA512:
+  metadata.gz: 1ffa616b4cadc9b82043e156ffe6c16b9e32bd9cdc25a131be8f1dafba72f5e17cb2fcc36fea88dcbd0008efdcd2a8480bd9e801a0b9f493f637baeb4fc624e7
+  data.tar.gz: 48487fd1ce5ef02a6b6cba144602baebad61b6bef0a9eadd57695d3f9338f1385fc0661589e632dbb2527e60154438c2df2eeb84f0d1e9acd6a4aa292bb46301

data/README.md

@@ -0,0 +1,206 @@
+# easy-peasy-api
+
+Filesystem-based API routing for Rails. Drop controller files into a directory and they become API endpoints automatically. No `routes.rb` entries needed.
+
+## Install
+
+```ruby
+# Gemfile
+gem "easy-peasy-api", require: "easy_peasy_api"
+```
+
+```ruby
+# config/initializers/easy_peasy_api.rb
+EasyPeasyApi.configure do |config|
+  config.path = "/api/v1"
+end
+```
+
+That's it. Every controller under `app/controllers/api/v1/` is now a live endpoint.
+
+## How it works
+
+The URL maps directly to the filesystem. The HTTP method determines the action.
+
+```
+URL                                    Controller File                                          Action
+─────────────────────────────────────  ─────────────────────────────────────────────────────────  ──────
+GET    /api/v1/customers              app/controllers/api/v1/customers_controller.rb             #index
+POST   /api/v1/customers              app/controllers/api/v1/customers_controller.rb             #create
+GET    /api/v1/customers/42           app/controllers/api/v1/customers_controller.rb             #show
+PUT    /api/v1/customers/42           app/controllers/api/v1/customers_controller.rb             #update
+DELETE /api/v1/customers/42           app/controllers/api/v1/customers_controller.rb             #destroy
+```
+
+Nest directories for nested resources:
+
+```
+GET    /api/v1/customers/uncontacted      app/controllers/api/v1/customers/uncontacted_controller.rb   #index
+GET    /api/v1/customers/uncontacted/7    app/controllers/api/v1/customers/uncontacted_controller.rb   #show
+```
+
+Dynamic segments in the middle just work:
+
+```
+GET    /api/v1/customers/42/notes         app/controllers/api/v1/customers/notes_controller.rb         #index
+GET    /api/v1/customers/42/notes/99      app/controllers/api/v1/customers/notes_controller.rb         #show
+```
+
+The `42` becomes `params[:customer_id]` (singularized parent directory + `_id`). The `99` becomes `params[:id]`.
+
+## Examples
+
+### Basic controller
+
+```ruby
+# app/controllers/api/v1/customers_controller.rb
+module Api::V1
+  class CustomersController < ActionController::API
+    def index
+      render json: Customer.all
+    end
+
+    def show
+      render json: Customer.find(params[:id])
+    end
+
+    def create
+      customer = Customer.create!(customer_params)
+      render json: customer, status: :created
+    end
+
+    def update
+      customer = Customer.find(params[:id])
+      customer.update!(customer_params)
+      render json: customer
+    end
+
+    def destroy
+      Customer.find(params[:id]).destroy!
+      head :no_content
+    end
+
+    private
+
+    def customer_params
+      params.permit(:name, :email)
+    end
+  end
+end
+```
+
+```
+curl localhost:3000/api/v1/customers
+curl localhost:3000/api/v1/customers/42
+curl -X POST localhost:3000/api/v1/customers -d '{"name":"Acme"}' -H 'Content-Type: application/json'
+```
+
+### Nested resource with dynamic parent ID
+
+```ruby
+# app/controllers/api/v1/customers/notes_controller.rb
+module Api::V1::Customers
+  class NotesController < ActionController::API
+    def index
+      customer = Customer.find(params[:customer_id])
+      render json: customer.notes
+    end
+
+    def show
+      note = Note.find(params[:id])
+      render json: note
+    end
+  end
+end
+```
+
+```
+curl localhost:3000/api/v1/customers/42/notes          # params[:customer_id] = "42"
+curl localhost:3000/api/v1/customers/42/notes/99       # params[:customer_id] = "42", params[:id] = "99"
+```
+
+### Deeper nesting
+
+```ruby
+# app/controllers/api/v1/customers/uncontacted/notes_controller.rb
+module Api::V1::Customers::Uncontacted
+  class NotesController < ActionController::API
+    def index
+      render json: Note.where(uncontacted_id: params[:uncontacted_id])
+    end
+
+    def show
+      render json: Note.find(params[:id])
+    end
+  end
+end
+```
+
+```
+curl localhost:3000/api/v1/customers/uncontacted/55/notes       # params[:uncontacted_id] = "55"
+curl localhost:3000/api/v1/customers/uncontacted/55/notes/12    # params[:uncontacted_id] = "55", params[:id] = "12"
+```
+
+### Renaming params with `set_params`
+
+Dynamic segments are auto-named after the parent directory (singularized + `_id`). Sometimes that default name doesn't match your domain. Inherit from `EasyPeasyApi::ApplicationController` and call `set_params` in the action to rename them:
+
+```ruby
+# app/controllers/api/v1/customers/notes_controller.rb
+#
+# URL: /api/v1/customers/42/notes/99
+# Default params: customer_id=42, id=99
+# After set_params: account_id=42, id=99
+module Api::V1::Customers
+  class NotesController < EasyPeasyApi::ApplicationController
+    def index
+      set_params :account_id
+      render json: Note.where(account_id: params[:account_id])
+    end
+
+    def show
+      set_params :account_id, :id
+      render json: Note.find_by(account_id: params[:account_id], id: params[:id])
+    end
+  end
+end
+```
+
+```
+curl localhost:3000/api/v1/customers/42/notes
+# Without set_params: params[:customer_id] = "42"
+# With set_params:    params[:account_id] = "42"
+```
+
+`set_params` maps names to dynamic segment values in the order they appear in the URL. Call it in the action, or in a `before_action`. It rebuilds params each time, so you can call it as many times as you need.
+
+## Param naming rules
+
+| URL pattern | Default param name | Rule |
+|---|---|---|
+| `/customers/42` | `params[:id]` | Trailing segment after a controller |
+| `/customers/42/notes` | `params[:customer_id]` | Mid-path segment, named from parent dir (singularized + `_id`) |
+| `/customers/42/notes/99` | `params[:customer_id]`, `params[:id]` | Both rules combined |
+
+## Route priority
+
+When a URL segment could match either a nested controller or a dynamic `:id`, the more specific match (nested controller) wins:
+
+```
+app/controllers/api/v1/customers_controller.rb
+app/controllers/api/v1/customers/uncontacted_controller.rb
+```
+
+```
+GET /api/v1/customers/uncontacted   -> UncontactedController#index  (not CustomersController#show)
+GET /api/v1/customers/42            -> CustomersController#show     (no matching nested controller)
+```
+
+## Action mapping
+
+| HTTP method | With `:id` | Without `:id` |
+|---|---|---|
+| GET | `show` | `index` |
+| POST | -- | `create` |
+| PUT / PATCH | `update` | -- |
+| DELETE | `destroy` | -- |

data/lib/easy_peasy_api/application_controller.rb

@@ -0,0 +1,41 @@
+module EasyPeasyApi
+  class ApplicationController < ActionController::API
+    before_action :set_default_params
+
+    private
+
+    # Called automatically. Applies the middleware's default param names.
+    def set_default_params
+      default_names = request.env['easy_peasy_api.default_param_names']
+      values = request.env['easy_peasy_api.dynamic_values']
+      return unless default_names && values
+
+      set_params(*default_names)
+    end
+
+    # Rebuild path_parameters with the given names mapped to the ordered
+    # dynamic segment values the middleware extracted from the URL.
+    #
+    # Call this inside any action (or a before_action) to rename params:
+    #
+    #   def show
+    #     set_params :customer_id, :id
+    #   end
+    #
+    def set_params(*names)
+      values = request.env['easy_peasy_api.dynamic_values']
+      return unless values
+
+      path_params = {
+        controller: request.path_parameters[:controller],
+        action: request.path_parameters[:action]
+      }
+
+      names.each_with_index do |name, i|
+        path_params[name.to_sym] = values[i] if i < values.length
+      end
+
+      request.path_parameters = path_params
+    end
+  end
+end

data/lib/easy_peasy_api/configuration.rb

@@ -0,0 +1,34 @@
+module EasyPeasyApi
+  class Configuration
+    attr_accessor :path
+
+    def initialize
+      @path = nil
+    end
+
+    # Returns the path with leading slash, no trailing slash
+    def normalized_path
+      return nil unless @path
+
+      p = @path.to_s
+      p = "/#{p}" unless p.start_with?('/')
+      p.chomp('/')
+    end
+
+    # Converts the configured path to a module prefix
+    # e.g. "/api/v1" => "Api::V1"
+    def controller_module_prefix
+      return nil unless normalized_path
+
+      normalized_path.delete_prefix('/').split('/').map { |s| s.camelize }.join('::')
+    end
+
+    # Returns the filesystem directory under app/controllers for this path
+    # e.g. "/api/v1" => "api/v1"
+    def controller_directory
+      return nil unless normalized_path
+
+      normalized_path.delete_prefix('/')
+    end
+  end
+end

data/lib/easy_peasy_api/middleware.rb

@@ -0,0 +1,151 @@
+require 'action_dispatch'
+require 'active_support/inflector'
+
+module EasyPeasyApi
+  class Middleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      config = EasyPeasyApi.configuration
+      prefix = config&.normalized_path
+
+      return @app.call(env) unless prefix
+
+      request_path = env['PATH_INFO'].to_s
+
+      return @app.call(env) unless path_matches?(request_path, prefix)
+
+      relative = request_path.delete_prefix(prefix).delete_prefix('/')
+      return @app.call(env) if relative.empty?
+
+      segments = relative.split('/').reject(&:empty?)
+      return @app.call(env) if segments.empty?
+
+      resolution = resolve(segments, config)
+      return not_found unless resolution
+
+      controller_class, dynamic_pairs = resolution
+
+      # dynamic_pairs is an ordered array of [default_name, value]
+      # e.g. [[:uncontacted_id, "234234"], [:id, "999"]]
+      has_id = dynamic_pairs.any? { |name, _| name == :id }
+
+      request_method = env['REQUEST_METHOD']
+      action = determine_action(request_method, has_id)
+      return method_not_allowed unless action
+
+      dispatch(controller_class, action, dynamic_pairs, env)
+    end
+
+    private
+
+    def path_matches?(request_path, prefix)
+      request_path == prefix || request_path.start_with?("#{prefix}/")
+    end
+
+    def resolve(segments, config)
+      controllers_root = Rails.root.join('app', 'controllers', config.controller_directory).to_s
+      mod_prefix = config.controller_module_prefix
+
+      result = walk(segments, controllers_root, [], [], nil)
+      return nil unless result
+
+      controller_segments, dynamic_pairs = result
+      klass = constantize_controller(mod_prefix, controller_segments)
+      return nil unless klass
+
+      [klass, dynamic_pairs]
+    end
+
+    # Recursive filesystem walk.
+    #
+    # Returns [controller_segments, dynamic_pairs] where dynamic_pairs is
+    # an ordered array of [default_param_name, value].
+    def walk(segments, current_dir, controller_segments, dynamic_pairs, last_dir_name)
+      return nil if segments.empty?
+
+      segment = segments.first
+      rest = segments[1..]
+
+      controller_file = File.join(current_dir, "#{segment}_controller.rb")
+      has_controller = File.exist?(controller_file)
+      subdir = File.join(current_dir, segment)
+      has_directory = File.directory?(subdir)
+
+      # 1. Try descending into a subdirectory first (most specific match wins)
+      if has_directory
+        result = walk(rest, subdir, controller_segments + [segment], dynamic_pairs, segment)
+        return result if result
+      end
+
+      # 2. Try matching a controller file
+      if has_controller
+        found_segments = controller_segments + [segment]
+
+        if rest.empty?
+          return [found_segments, dynamic_pairs]
+        elsif rest.length == 1
+          return [found_segments, dynamic_pairs + [[:id, rest.first]]]
+        end
+      end
+
+      # 3. No directory or controller match — dynamic param
+      if last_dir_name
+        param_name = :"#{last_dir_name.singularize}_id"
+        return walk(rest, current_dir, controller_segments, dynamic_pairs + [[param_name, segment]], last_dir_name)
+      end
+
+      nil
+    end
+
+    def constantize_controller(mod_prefix, segments)
+      class_name = segments.map { |s| s.camelize }.join('::')
+      full_name = "#{mod_prefix}::#{class_name}Controller"
+      full_name.constantize
+    rescue NameError
+      nil
+    end
+
+    def dispatch(controller_class, action, dynamic_pairs, env)
+      default_names = dynamic_pairs.map(&:first)
+      values = dynamic_pairs.map(&:last)
+
+      # Store ordered data for set_params
+      env['easy_peasy_api.dynamic_values'] = values
+      env['easy_peasy_api.default_param_names'] = default_names
+
+      # Set path_parameters with default names so it works out of the box
+      path_params = { controller: controller_class.controller_path, action: action.to_s }
+      dynamic_pairs.each { |name, value| path_params[name] = value }
+
+      env['action_dispatch.request.path_parameters'] = path_params
+
+      controller_class.action(action).call(env)
+    end
+
+    def determine_action(method, has_id)
+      if has_id
+        case method
+        when 'GET'          then :show
+        when 'PUT', 'PATCH' then :update
+        when 'DELETE'       then :destroy
+        end
+      else
+        case method
+        when 'GET'  then :index
+        when 'POST' then :create
+        end
+      end
+    end
+
+    def not_found
+      [404, { 'content-type' => 'application/json' }, ['{"error":"Not Found"}']]
+    end
+
+    def method_not_allowed
+      [405, { 'content-type' => 'application/json' }, ['{"error":"Method Not Allowed"}']]
+    end
+  end
+end

data/lib/easy_peasy_api/railtie.rb

@@ -0,0 +1,9 @@
+require 'rails/railtie'
+
+module EasyPeasyApi
+  class Railtie < Rails::Railtie
+    initializer 'easy_peasy_api.middleware' do |app|
+      app.middleware.use EasyPeasyApi::Middleware
+    end
+  end
+end

data/lib/easy_peasy_api/version.rb

@@ -0,0 +1,3 @@
+module EasyPeasyApi
+  VERSION = "0.1.0"
+end

data/lib/easy_peasy_api/version.rb.erb

@@ -0,0 +1,3 @@
+module EasyPeasyApi
+  VERSION = "<%= version %>"
+end

data/lib/easy_peasy_api.rb

@@ -0,0 +1,22 @@
+require 'easy_peasy_api/version'
+require 'easy_peasy_api/configuration'
+require 'easy_peasy_api/middleware'
+require 'easy_peasy_api/railtie' if defined?(Rails::Railtie)
+
+module EasyPeasyApi
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end
+
+require 'easy_peasy_api/application_controller' if defined?(ActionController::API)

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: easy-peasy-api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nathan
+bindir: bin
+cert_chain: []
+date: 1980-01-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: A Rails Railtie that dynamically routes API requests to controllers based
+  on the filesystem structure.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/easy_peasy_api.rb
+- lib/easy_peasy_api/application_controller.rb
+- lib/easy_peasy_api/configuration.rb
+- lib/easy_peasy_api/middleware.rb
+- lib/easy_peasy_api/railtie.rb
+- lib/easy_peasy_api/version.rb
+- lib/easy_peasy_api/version.rb.erb
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Filesystem-based API routing for Rails
+test_files: []