Implement ProfileApiClient.create_school_student

TODO: Better support for 422 responses from Profile API - at the very
least for the `ERR_USER_EXISTS` error.

Author: chrisroos

lib/concepts/school_student/create.rb

@@ -16,14 +16,13 @@ def call(school:, school_student_params:, token:)
       private
 
       def create_student(school, school_student_params, token)
-        organisation_id = school.id
         username = school_student_params.fetch(:username)
         password = school_student_params.fetch(:password)
         name = school_student_params.fetch(:name)
 
         validate(school:, username:, password:, name:)
 
-        ProfileApiClient.create_school_student(token:, username:, password:, name:, organisation_id:)
+        ProfileApiClient.create_school_student(token:, username:, password:, name:, school:)
       end
 
       def validate(school:, username:, password:, name:)

lib/concepts/school_student/create_batch.rb

@@ -23,7 +23,7 @@ def create_batch(school, uploaded_file, token)
         validate(school:, sheet:)
 
         non_header_rows_with_content(sheet:).each do |name, username, password|
-          ProfileApiClient.create_school_student(token:, username:, password:, name:, organisation_id: school.id)
+          ProfileApiClient.create_school_student(token:, username:, password:, name:, school:)
         end
       end
 

lib/profile_api_client.rb

@@ -147,19 +147,30 @@ def list_school_students(token:, organisation_id:)
     # The API should respond:
     # - 404 Not Found if the user doesn't exist
     # - 422 Unprocessable if the constraints are not met
-    def create_school_student(token:, username:, password:, name:, organisation_id:)
+    # rubocop:disable Metrics/AbcSize
+    def create_school_student(token:, username:, password:, name:, school:)
       return nil if token.blank?
 
-      _ = username
-      _ = password
-      _ = name
-      _ = organisation_id
+      response = connection.post("/api/v1/schools/#{school.id}/students") do |request|
+        apply_default_headers(request, token)
+        request.body = [{
+          name:,
+          username:,
+          password:
+        }].to_json
+      end
 
-      # TODO: We should make Faraday raise a Ruby error for a non-2xx status
-      # code so that SchoolStudent::Create propagates the error in the response.
-      response = {}
-      response.deep_symbolize_keys
+      if response.status == 422
+        error_code = JSON.parse(response.body)['errors'].first['error']
+        message = error_code == 'ERR_USER_EXISTS' ? 'Username already exists' : "Unknown error code: #{error_code}"
+        raise "Student not created in Profile API. HTTP response code 422. #{message}"
+      end
+
+      raise "Student not created in Profile API. HTTP response code: #{response.status}" unless response.status == 201
+
+      JSON.parse(response.body)
     end
+    # rubocop:enable Metrics/AbcSize
 
     # The API should enforce these constraints:
     # - The token has the school-owner or school-teacher role for the given organisation ID

spec/concepts/school_student/create_batch_spec.rb

@@ -21,15 +21,15 @@
 
     # TODO: Replace with WebMock assertion once the profile API has been built.
     expect(ProfileApiClient).to have_received(:create_school_student)
-      .with(token:, username: 'jane123', password: 'secret123', name: 'Jane Doe', organisation_id: school.id)
+      .with(token:, username: 'jane123', password: 'secret123', name: 'Jane Doe', school:)
   end
 
   it "makes a profile API call to create John Doe's account" do
     described_class.call(school:, uploaded_file: file, token:)
 
     # TODO: Replace with WebMock assertion once the profile API has been built.
     expect(ProfileApiClient).to have_received(:create_school_student)
-      .with(token:, username: 'john123', password: 'secret456', name: 'John Doe', organisation_id: school.id)
+      .with(token:, username: 'john123', password: 'secret456', name: 'John Doe', school:)
   end
 
   context 'when an .xlsx file is provided' do

spec/concepts/school_student/create_spec.rb

@@ -28,7 +28,7 @@
 
     # TODO: Replace with WebMock assertion once the profile API has been built.
     expect(ProfileApiClient).to have_received(:create_school_student)
-      .with(token:, username: 'student-to-create', password: 'at-least-8-characters', name: 'School Student', organisation_id: school.id)
+      .with(token:, username: 'student-to-create', password: 'at-least-8-characters', name: 'School Student', school:)
   end
 
   context 'when creation fails' do

spec/lib/profile_api_client_spec.rb

@@ -287,4 +287,80 @@ def delete_safeguarding_flag
       described_class.delete_safeguarding_flag(token:, flag:)
     end
   end
+
+  describe '.create_school_student' do
+    let(:username) { 'username' }
+    let(:password) { 'password' }
+    let(:name) { 'name' }
+    let(:school) { build(:school, id: SecureRandom.uuid) }
+    let(:create_students_url) { "#{api_url}/api/v1/schools/#{school.id}/students" }
+
+    before do
+      stub_request(:post, create_students_url).to_return(status: 201, body: '{}')
+    end
+
+    it 'makes a request to the profile api host' do
+      create_school_student
+      expect(WebMock).to have_requested(:post, create_students_url)
+    end
+
+    it 'includes token in the authorization request header' do
+      create_school_student
+      expect(WebMock).to have_requested(:post, create_students_url).with(headers: { authorization: "Bearer #{token}" })
+    end
+
+    it 'includes the profile api key in the x-api-key request header' do
+      create_school_student
+      expect(WebMock).to have_requested(:post, create_students_url).with(headers: { 'x-api-key' => api_key })
+    end
+
+    it 'sets content-type of request to json' do
+      create_school_student
+      expect(WebMock).to have_requested(:post, create_students_url).with(headers: { 'content-type' => 'application/json' })
+    end
+
+    it 'sets accept header to json' do
+      create_school_student
+      expect(WebMock).to have_requested(:post, create_students_url).with(headers: { 'accept' => 'application/json' })
+    end
+
+    it 'returns the id of the created student(s) if successful' do
+      data = { 'created' => ['student-id'] }
+      stub_request(:post, create_students_url)
+        .to_return(status: 201, body: data.to_json)
+      expect(create_school_student).to eq(data)
+    end
+
+    it 'raises exception with details of the error if 422 response indicates that the user already exists' do
+      response = { 'errors' => [{ 'username' => 'jdoe', 'error' => 'ERR_USER_EXISTS' }] }
+      stub_request(:post, create_students_url)
+        .to_return(status: 422, body: response.to_json)
+      expect { create_school_student }.to raise_error('Student not created in Profile API. HTTP response code 422. Username already exists')
+    end
+
+    it 'raises exception including the error code if 422 response indicates that some other error occurred' do
+      response = { 'errors' => [{ 'username' => 'jdoe', 'error' => 'ERR_UNKNOWN' }] }
+      stub_request(:post, create_students_url)
+        .to_return(status: 422, body: response.to_json)
+      expect { create_school_student }.to raise_error('Student not created in Profile API. HTTP response code 422. Unknown error code: ERR_UNKNOWN')
+    end
+
+    it 'raises exception if anything other than a 201 status code is returned' do
+      stub_request(:post, create_students_url)
+        .to_return(status: 200)
+
+      expect { create_school_student }.to raise_error(RuntimeError)
+    end
+
+    it 'includes details of underlying response when exception is raised' do
+      stub_request(:post, create_students_url)
+        .to_return(status: 401)
+
+      expect { create_school_student }.to raise_error('Student not created in Profile API. HTTP response code: 401')
+    end
+
+    def create_school_student
+      described_class.create_school_student(token:, username:, password:, name:, school:)
+    end
+  end
 end