feat: add Party management API with RESTful endpoints and comprehensive documentation

- Introduce Party model with lifecycle states (draft, published, canceled, sold_out)
- Add RESTful API endpoints under /api/v1/parties for CRUD operations
- Create ApiController base with API key authentication
- Implement comprehensive code comments across models and controllers
- Add database migration for parties table with proper indexes
- Configure API routes with namespaced versioning

app/controllers/api/v1/parties_controller.rb

@@ -0,0 +1,82 @@
+# API controller for managing party resources
+# Provides RESTful endpoints for CRUD operations on Party model
+module Api
+  module V1
+    class PartiesController < ApiController
+      # Load party before specific actions to reduce duplication
+      before_action :set_party, only: [:show, :update, :destroy]
+
+      # GET /api/v1/parties
+      # Returns all parties sorted by creation date (newest first)
+      def index
+        @parties = Party.all.order(created_at: :desc)
+        render json: @parties, status: :ok
+      end
+
+      # GET /api/v1/parties/:id
+      # Returns a single party by ID
+      # Returns 404 if party is not found
+      def show
+        render json: @party, status: :ok
+      end
+
+      # POST /api/v1/parties
+      # Creates a new party with provided attributes
+      # Returns 201 Created on success with party data
+      # Returns 422 Unprocessable Entity with validation errors on failure
+      def create
+        @party = Party.new(party_params)
+        if @party.save
+          render json: @party, status: :created
+        else
+          render json: { errors: @party.errors.full_messages }, status: :unprocessable_entity
+        end
+      end
+
+      # PATCH/PUT /api/v1/parties/:id
+      # Updates an existing party with provided attributes
+      # Returns 200 OK with updated party data on success
+      # Returns 422 Unprocessable Entity with validation errors on failure
+      def update
+        if @party.update(party_params)
+          render json: @party, status: :ok
+        else
+          render json: { errors: @party.errors.full_messages }, status: :unprocessable_entity
+        end
+      end
+
+      # DELETE /api/v1/parties/:id
+      # Permanently deletes a party
+      # Returns 204 No Content on success
+      def destroy
+        @party.destroy
+        head :no_content
+      end
+
+      private
+
+      # Finds a party by ID or returns 404 Not Found
+      # Used as before_action for show, update, and destroy actions
+      def set_party
+        @party = Party.find(params[:id])
+      rescue ActiveRecord::RecordNotFound
+        render json: { error: "Party not found" }, status: :not_found
+      end
+
+      # Strong parameters for party creation and updates
+      # Whitelists permitted attributes to prevent mass assignment vulnerabilities
+      def party_params
+        params.require(:party).permit(
+          :name,
+          :description,
+          :state,
+          :venue_name,
+          :venue_address,
+          :latitude,
+          :longitude,
+          :featured
+        )
+      end
+    end
+  end
+end