feat(api): implement response envelope, error handling, and sparse fieldsets

New concerns and modules:
- ApiPublic::ResponseEnvelope - Standardized response format with
  render_envelope, pagination meta, and HATEOAS links helpers
- ApiPublic::ErrorHandler - rescue_from handlers with standardized
  error format including error codes and request IDs
- ApiPublic::SparseFieldsets - fields parameter for requesting only
  specific fields to reduce payload size
- ApiPublic::Errors - Custom error classes (ValidationError,
  PropertyNotFoundError, RateLimitedError, etc.)

Updated BaseController to include all new concerns.
Added error_handling_spec.rb for testing error responses.

All existing API tests pass (27+ examples).

Author: etewiah

app/controllers/api_public/v1/base_controller.rb

@@ -1,7 +1,14 @@
+# frozen_string_literal: true
+
+require_dependency "api_public/errors"
+
 module ApiPublic
   module V1
     class BaseController < ActionController::Base
       include SubdomainTenant
+      include ApiPublic::ResponseEnvelope
+      include ApiPublic::ErrorHandler
+      include ApiPublic::SparseFieldsets
 
       skip_before_action :verify_authenticity_token
 
@@ -26,3 +33,4 @@ def set_api_public_cache_headers
     end
   end
 end
+

app/controllers/concerns/api_public/error_handler.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module ApiPublic
+  # Concern for standardized error handling across API controllers
+  # Provides rescue handlers and error rendering
+  module ErrorHandler
+    extend ActiveSupport::Concern
+
+    included do
+      # Rescue from custom API errors
+      rescue_from ApiPublic::Errors::ApiError, with: :render_api_error
+
+      # Rescue from ActiveRecord errors
+      rescue_from ActiveRecord::RecordNotFound, with: :render_not_found
+      rescue_from ActiveRecord::RecordInvalid, with: :render_validation_error
+
+      # Rescue from parameter errors
+      rescue_from ActionController::ParameterMissing, with: :render_parameter_missing
+    end
+
+    private
+
+    # Render a standardized API error response
+    def render_api_error(error)
+      # Add request ID for debugging
+      error_response = {
+        error: error.to_h.merge(request_id: request.uuid)
+      }
+
+      # Add retry-after header for rate limiting
+      if error.is_a?(ApiPublic::Errors::RateLimitedError)
+        response.headers["Retry-After"] = error.retry_after.to_s
+      end
+
+      render json: error_response, status: error.status
+    end
+
+    # Handle ActiveRecord::RecordNotFound
+    def render_not_found(exception)
+      model_name = exception.model || "Resource"
+      message = "#{model_name} not found"
+
+      render json: {
+        error: {
+          code: "NOT_FOUND",
+          message: message,
+          status: 404,
+          request_id: request.uuid
+        }
+      }, status: :not_found
+    end
+
+    # Handle ActiveRecord::RecordInvalid
+    def render_validation_error(exception)
+      errors = exception.record&.errors&.to_hash || {}
+
+      render json: {
+        error: {
+          code: "VALIDATION_FAILED",
+          message: "Validation failed",
+          status: 422,
+          details: { validation_errors: errors },
+          request_id: request.uuid
+        }
+      }, status: :unprocessable_entity
+    end
+
+    # Handle ActionController::ParameterMissing
+    def render_parameter_missing(exception)
+      render json: {
+        error: {
+          code: "VALIDATION_FAILED",
+          message: "Missing required parameter: #{exception.param}",
+          status: 400,
+          details: { missing_param: exception.param.to_s },
+          request_id: request.uuid
+        }
+      }, status: :bad_request
+    end
+
+    # Generic 404 helper
+    def render_not_found_error(message = "Resource not found", code: "NOT_FOUND")
+      render json: {
+        error: {
+          code: code,
+          message: message,
+          status: 404,
+          request_id: request.uuid
+        }
+      }, status: :not_found
+    end
+
+    # Generic 400 helper
+    def render_bad_request(message, code: "BAD_REQUEST", details: {})
+      render json: {
+        error: {
+          code: code,
+          message: message,
+          status: 400,
+          details: details.presence,
+          request_id: request.uuid
+        }.compact
+      }, status: :bad_request
+    end
+  end
+end

app/controllers/concerns/api_public/response_envelope.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module ApiPublic
+  # Concern for standardized API response envelopes
+  # Provides consistent response format across all endpoints
+  #
+  # Standard envelope format:
+  # {
+  #   "data": { ... } | [...],
+  #   "meta": { "total": 100, "page": 1, ... },
+  #   "_links": { "self": "/...", "next": "/..." },
+  #   "_errors": []
+  # }
+  module ResponseEnvelope
+    extend ActiveSupport::Concern
+
+    private
+
+    # Render a standardized response envelope
+    #
+    # @param data [Hash, Array] The primary response data
+    # @param meta [Hash] Pagination and metadata (optional)
+    # @param links [Hash] HATEOAS-style links (optional)
+    # @param errors [Array] Partial failure errors (optional)
+    # @param status [Symbol, Integer] HTTP status (default: :ok)
+    def render_envelope(data:, meta: nil, links: nil, errors: nil, status: :ok)
+      response = { data: data }
+      response[:meta] = meta if meta.present?
+      response[:_links] = links if links.present?
+      response[:_errors] = errors if errors.present? && errors.any?
+
+      render json: response, status: status
+    end
+
+    # Build pagination meta from a collection
+    #
+    # @param total [Integer] Total count of items
+    # @param page [Integer] Current page number
+    # @param per_page [Integer] Items per page
+    # @return [Hash] Pagination metadata
+    def build_pagination_meta(total:, page:, per_page:)
+      total_pages = per_page.positive? ? (total.to_f / per_page).ceil : 0
+
+      {
+        total: total,
+        page: page,
+        per_page: per_page,
+        total_pages: total_pages
+      }
+    end
+
+    # Build HATEOAS-style pagination links
+    #
+    # @param base_path [String] Base URL path for the resource
+    # @param page [Integer] Current page number
+    # @param total_pages [Integer] Total number of pages
+    # @param query_params [Hash] Additional query parameters
+    # @return [Hash] Navigation links
+    def build_pagination_links(base_path:, page:, total_pages:, query_params: {})
+      links = {
+        self: build_page_url(base_path, page, query_params)
+      }
+
+      links[:first] = build_page_url(base_path, 1, query_params) if page > 1
+      links[:prev] = build_page_url(base_path, page - 1, query_params) if page > 1
+      links[:next] = build_page_url(base_path, page + 1, query_params) if page < total_pages
+      links[:last] = build_page_url(base_path, total_pages, query_params) if page < total_pages
+
+      links
+    end
+
+    # Build a URL with page parameter
+    def build_page_url(base_path, page, query_params)
+      params = query_params.merge(page: page)
+      query_string = params.to_query
+      query_string.present? ? "#{base_path}?#{query_string}" : base_path
+    end
+
+    # Render a success response with optional message
+    def render_success(message: nil, data: nil, status: :ok)
+      response = { success: true }
+      response[:message] = message if message
+      response[:data] = data if data
+
+      render json: response, status: status
+    end
+
+    # Render a created response (201)
+    def render_created(data:, location: nil)
+      response = { data: data }
+      headers["Location"] = location if location
+
+      render json: response, status: :created
+    end
+  end
+end

app/controllers/concerns/api_public/sparse_fieldsets.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module ApiPublic
+  # Concern for sparse fieldsets - allows clients to request only specific fields
+  # Reduces payload size for bandwidth-constrained clients
+  #
+  # Usage:
+  #   GET /api_public/v1/en/properties?fields=id,slug,title,primary_image_url
+  #
+  module SparseFieldsets
+    extend ActiveSupport::Concern
+
+    private
+
+    # Filter a hash to only include specified fields
+    #
+    # @param data [Hash] The full data hash
+    # @param allowed_fields [Array<Symbol>] Fields allowed to be requested
+    # @return [Hash] Filtered hash with only requested fields
+    def apply_sparse_fieldsets(data, allowed_fields:)
+      requested_fields = parse_fields_param
+      return data if requested_fields.blank?
+
+      # Only allow whitelisted fields
+      valid_fields = requested_fields & allowed_fields.map(&:to_s)
+      return data if valid_fields.blank?
+
+      # Filter the data
+      data.slice(*valid_fields.map(&:to_sym))
+    end
+
+    # Apply sparse fieldsets to an array of records
+    #
+    # @param records [Array<Hash>] Array of record hashes
+    # @param allowed_fields [Array<Symbol>] Fields allowed to be requested
+    # @return [Array<Hash>] Array with filtered records
+    def apply_sparse_fieldsets_to_collection(records, allowed_fields:)
+      requested_fields = parse_fields_param
+      return records if requested_fields.blank?
+
+      # Only allow whitelisted fields
+      valid_fields = requested_fields & allowed_fields.map(&:to_s)
+      return records if valid_fields.blank?
+
+      # Filter each record
+      records.map { |record| record.slice(*valid_fields.map(&:to_sym)) }
+    end
+
+    # Parse the fields parameter from request
+    #
+    # @return [Array<String>] List of requested field names
+    def parse_fields_param
+      return [] unless params[:fields].present?
+
+      params[:fields].to_s.split(",").map(&:strip).reject(&:blank?)
+    end
+
+    # Check if sparse fieldsets are requested
+    def sparse_fieldsets_requested?
+      params[:fields].present?
+    end
+
+    # Property fields that can be requested via sparse fieldsets
+    PROPERTY_ALLOWED_FIELDS = %i[
+      id
+      slug
+      reference
+      title
+      description
+      price_sale_current_cents
+      price_rental_monthly_current_cents
+      formatted_price
+      currency
+      count_bedrooms
+      count_bathrooms
+      count_garages
+      constructed_area
+      area_unit
+      for_sale
+      for_rent
+      highlighted
+      latitude
+      longitude
+      primary_image_url
+      prop_photos
+      created_at
+      updated_at
+    ].freeze
+
+    # Link fields that can be requested via sparse fieldsets
+    LINK_ALLOWED_FIELDS = %i[
+      id
+      slug
+      title
+      url
+      position
+      order
+      visible
+      external
+    ].freeze
+
+    # Testimonial fields that can be requested via sparse fieldsets
+    TESTIMONIAL_ALLOWED_FIELDS = %i[
+      id
+      name
+      role
+      company
+      content
+      rating
+      avatar_url
+      featured
+      visible
+    ].freeze
+  end
+end