api call for getting course sections, optionally with students

refs #4156

Change-Id: I8d7da2073b6063e14727c7faa6ba90e1809efa81
Reviewed-on: https://gerrit.instructure.com/3004
Reviewed-by: Brian Whitmer <brian@instructure.com>
Tested-by: Hudson <hudson@instructure.com>

app/controllers/courses_controller.rb

@@ -131,6 +131,50 @@ class CoursesController < ApplicationController
     end
   end
 
+  STUDENT_API_FIELDS = %w(id name)
+
+  # @API
+  # Returns the list of sections for this course.
+  #
+  # @argument include[] ["students"] Associations to include with the group.
+  #
+  # @response_field id The unique identifier for the course section.
+  # @response_field name The name of the section.
+  #
+  # @example_response
+  #   ?include[]=students
+  #
+  # [
+  #   {
+  #     "id": 1,
+  #     "name": "Section A",
+  #     "students": [...]
+  #   },
+  #   {
+  #     "id": 2,
+  #     "name": "Section B",
+  #     "students": [...]
+  #   }
+  # ]
+  def sections
+    get_context
+    if authorized_action(@context, @current_user, :read_roster)
+      includes = Array(params[:include])
+      include_students = includes.include?('students')
+
+      result = @context.course_sections.map do |section|
+        res = section.as_json(:include_root => false,
+                              :only => %w(id name))
+        if include_students
+          res['students'] = section.enrollments.all(:conditions => "type = 'StudentEnrollment'").map { |e| e.user.as_json(:include_root => false, :only => STUDENT_API_FIELDS) }
+        end
+        res
+      end
+
+      render :json => result
+    end
+  end
+
   # @API
   # Returns the list of students enrolled in this course.
   #
@@ -144,7 +188,7 @@ class CoursesController < ApplicationController
     get_context
     if authorized_action(@context, @current_user, :read_roster)
       render :json => @context.students.to_json(:include_root => false,
-                                                :only => %w(id name))
+                                                :only => STUDENT_API_FIELDS)
     end
   end
 

config/routes.rb

@@ -613,6 +613,9 @@ ActionController::Routing::Routes.draw do |map|
       course.students 'students.:format',
         :controller => 'courses', :action => 'students',
         :conditions => { :method => :get }
+      course.sections 'sections.:format',
+        :controller => 'courses', :action => 'sections',
+        :conditions => { :method => :get }
       course.resources :assignments,
                         :controller => 'assignments_api',
                         :only => %w(show index create update) do |assignment|

spec/apis/v1/courses_api_spec.rb

@@ -69,6 +69,20 @@ describe CoursesController, :type => :integration do
         :only => %w(id name))
   end
 
+  it "should return the list of sections for the course" do
+    user1 = @user
+    user2 = User.create!(:name => 'Zombo')
+    section1 = @course2.default_section
+    section2 = @course2.course_sections.create!(:name => 'Section B')
+    @course2.enroll_user(user2, 'StudentEnrollment', :section => section2).accept!
+
+    json = api_call(:get, "/api/v1/courses/#{@course2.id}/sections.json",
+            { :controller => 'courses', :action => 'sections', :course_id => @course2.id.to_s, :format => 'json' }, { :include => ['students'] })
+    json.size.should == 2
+    json.find { |s| s['name'] == section1.name }['students'].should == api_json_response([user1], :only => %w(id name))
+    json.find { |s| s['name'] == section2.name }['students'].should == api_json_response([user2], :only => %w(id name))
+  end
+
   it "should return the needs_grading_count for all assignments" do
     @group = @course1.assignment_groups.create!({:name => "some group"})
     @assignment = @course1.assignments.create!(:title => "some assignment", :assignment_group => @group, :points_possible => 12)