restore conversations/find_recipients API route, fixes #9914

ensure legacy API route is still available (and added spec). minor doc
tweaks/fixes

test plan:

1. find conversation recipients through the web UI
2. find recipients by hitting the following URLs directly:
   * /api/v1/search/recipients
   * /api/v1/conversations/find_recipients
3. find recipients using the iPad app
4. it should all work

Change-Id: Ic283b3f5bacb22aba7b077e300d96c07565b8cd0
Reviewed-on: https://gerrit.instructure.com/12887
Reviewed-by: Jon Jensen <jon@instructure.com>
Tested-by: Jenkins <jenkins@instructure.com>

app/controllers/conversations_controller.rb

@@ -525,6 +525,11 @@ class ConversationsController < ApplicationController
     end
   end
 
+  # @API Find recipients
+  #
+  # Deprecated, see the Find recipients endpoint in the Search API
+  def find_recipients; end
+
   def public_feed
     return unless get_feed_context(:only => [:user])
     @current_user = @context

app/controllers/search_controller.rb

@@ -16,6 +16,8 @@
 # with this program. If not, see <http://www.gnu.org/licenses/>.
 #
 
+# @API Search
+
 class SearchController < ApplicationController
   include SearchHelper
 
@@ -35,7 +37,8 @@ class SearchController < ApplicationController
 
   # @API Find recipients
   # Find valid recipients (users, courses and groups) that the current user
-  # can send messages to.
+  # can send messages to. The /api/v1/search/recipients path is the preferred
+  # endpoint, /api/v1/conversations/find_recipients is deprecated.
   #
   # Pagination is supported if an explicit type is given (but there is no last
   # link). If no type is given, results will be limited to 10 by default (can

config/routes.rb

@@ -824,6 +824,10 @@ ActionController::Routing::Routes.draw do |map|
     api.get 'users/:user_id/profile', :controller => :profile, :action => :settings
     api.get 'users/:user_id/avatars', :controller => :profile, :action => :profile_pics
 
+    # deprecated routes, second one is solely for YARD. preferred API is api/v1/search/recipients
+    api.get 'conversations/find_recipients', :controller => :search, :action => :recipients
+    api.get 'conversations/find_recipients', :controller => :conversations, :action => :find_recipients
+
     api.with_options(:controller => :conversations) do |conversations|
       conversations.get 'conversations', :action => :index
       conversations.post 'conversations', :action => :create

spec/apis/v1/conversations_api_spec.rb

@@ -869,4 +869,27 @@ describe ConversationsController, :type => :integration do
       })
     end
   end
+
+  context "recipients" do
+    before do
+      @group = @course.groups.create(:name => "the group")
+      @group.users = [@me, @bob, @joe]
+    end
+
+    it "should support the deprecated route" do
+      json = api_call(:get, "/api/v1/conversations/find_recipients.json?search=o",
+              { :controller => 'search', :action => 'recipients', :format => 'json', :search => 'o' })
+      json.each { |c| c.delete("avatar_url") }
+      json.should eql [
+        {"id" => "course_#{@course.id}", "name" => "the course", "type" => "context", "user_count" => 6},
+        {"id" => "section_#{@other_section.id}", "name" => "the other section", "type" => "context", "user_count" => 1, "context_name" => "the course"},
+        {"id" => "section_#{@course.default_section.id}", "name" => "the section", "type" => "context", "user_count" => 5, "context_name" => "the course"},
+        {"id" => "group_#{@group.id}", "name" => "the group", "type" => "context", "user_count" => 3, "context_name" => "the course"},
+        {"id" => @bob.id, "name" => "bob", "common_courses" => {@course.id.to_s => ["StudentEnrollment"]}, "common_groups" => {@group.id.to_s => ["Member"]}},
+        {"id" => @joe.id, "name" => "joe", "common_courses" => {@course.id.to_s => ["StudentEnrollment"]}, "common_groups" => {@group.id.to_s => ["Member"]}},
+        {"id" => @me.id, "name" => @me.name, "common_courses" => {@course.id.to_s => ["TeacherEnrollment"]}, "common_groups" => {@group.id.to_s => ["Member"]}},
+        {"id" => @tommy.id, "name" => "tommy", "common_courses" => {@course.id.to_s => ["StudentEnrollment"]}, "common_groups" => {}}
+      ]
+    end
+  end
 end