Add POST /api/v0/conversation endpoint

This commit introduces a 'create' action in 'Api::V0::ConversationsController' that instantiates an anonymous conversation,  delegates validation and persistence to 'Form::CreateQuestion' (thereby reusing our PII detection, length limits and pending‐question logic rather than reimplementing it), and returns either a 201 with the 'QuestionBlueprint' pending view or a 422 with ‘ValidationErrorBlueprint' JSON. We’ve scoped the existing ‘find_conversation' before_action to run on all actions except ‘create', avoiding a premature 404 on the initial POST, and added a private ‘question_params' method to explicitly require and permit the '{ question: { question: "..." } }' payload in line with our OpenAPI schema. Finally, we updated 'routes.rb' to expose the new POST '/api/v0/conversation' route and added comprehensive request specs covering authorization, success and error scenarios.

Author: Sunny-xyz

app/controllers/api/v0/conversations_controller.rb

@@ -2,6 +2,19 @@ class Api::V0::ConversationsController < ApplicationController
   before_action { authorise_user!(SignonUser::Permissions::CONVERSATION_API) }
   before_action :find_conversation, only: %i[show answer answer_feedback]
 
+  def create
+    conversation = Conversation.new
+
+    form = Form::CreateQuestion.new(conversation: conversation, user_question: question_params[:question])
+
+    if form.valid?
+      question = form.submit
+      render json: QuestionBlueprint.render(question, view: :pending), status: :created
+    else
+      render json: ValidationErrorBlueprint.render(message: "Could not create question", fields: form.errors.messages), status: :unprocessable_entity
+    end
+  end
+
   def show
     answered_questions = @conversation.questions.joins(:answer)
     pending_question = @conversation.questions.unanswered.last
@@ -49,4 +62,8 @@ def find_conversation
   def answer_feedback_params
     params.permit(:useful)
   end
+
+  def question_params
+    params.require(:question).permit(:question)
+  end
 end

config/routes.rb

@@ -145,6 +145,7 @@
 
   namespace :api, format: false, defaults: { format: "json" } do
     namespace :v0 do
+      post "/conversation", to: "conversations#create", as: :create_conversation
       get "/conversation/:conversation_id", to: "conversations#show", as: :show_conversation
       get "/conversation/:conversation_id/questions/:question_id/answer", to: "conversations#answer", as: :answer_question
       post "/conversation/:conversation_id/answers/:answer_id/feedback", to: "conversations#answer_feedback", as: :answer_feedback

spec/requests/api/v0/conversations_spec.rb

@@ -89,6 +89,53 @@
     end
   end
 
+  describe "POST :create" do
+    it_behaves_like "responds with forbidden if user doesn't have API user permission",
+                    :api_v0_create_conversation_path,
+                    :post do
+      let(:route_params) { [] }
+    end
+
+    context "when the question is valid" do
+      let(:payload) { { question: { question: "What is the capital of France?" } } }
+
+      it "creates a Conversation and a Question and returns 201" do
+        expect {
+          post api_v0_create_conversation_path, params: payload
+        }.to change(Conversation, :count).by(1)
+           .and change(Question, :count).by(1)
+
+        expect(response).to have_http_status(:created)
+      end
+
+      it "returns the pending‐question JSON shaped by the pending view" do
+        post api_v0_create_conversation_path, params: payload
+
+        q = Question.last
+        expected = QuestionBlueprint.render_as_json(q, view: :pending)
+        expect(JSON.parse(response.body)).to eq(expected)
+      end
+    end
+
+    context "when the question is invalid" do
+      let(:payload) { { question: { question: "" } } }
+
+      it "returns 422 Unprocessable Entity" do
+        post api_v0_create_conversation_path, params: payload
+        expect(response).to have_http_status(:unprocessable_entity)
+      end
+
+      it "returns the ValidationError JSON" do
+        post api_v0_create_conversation_path, params: payload
+
+        expect(JSON.parse(response.body)).to eq({
+          "message" => "Could not create question",
+          "fields"  => { "user_question" => [Form::CreateQuestion::USER_QUESTION_PRESENCE_ERROR_MESSAGE] }
+        })
+      end
+    end
+  end
+
   describe "GET :answer" do
     context "when an answer has been generated for the question" do
       let!(:answer) { create(:answer, question:) }