subjects.rb in panoptes-client-0.3.8

- old
+ new

@@ -14,9 +14,26 @@
 
         response = panoptes.paginate("/subjects", query)
         response.fetch("subjects")
       end
 
+      # Fetch a subject given filters (including permissions)
+      #
+      # @param subject_id [Integer]
+      # @param project_id [Integer]
+      # @return nil or the subject
+      def subject(subject_id, project_id: nil)
+        query = {}
+        query[:project_id] = project_id if project_id
+
+        response = panoptes.get("/subjects/#{subject_id}", query)
+        if response.fetch('subjects', []).count > 1
+          raise StandardError.new 'Unexpectedly many subjects returned'
+        end
+
+        response.fetch('subjects', []).fetch(0, nil)
+      end
+
       # Retire a subject for a workflow
       #
       # @todo Add this endpoint to the Apiary docs and add a see-reference here.
       # @param workflow_id [Integer] the ID of a workflow
       # @param subject_id  [Integer] the ID of a subject associated with that workflow (through one of the assigned subject_sets)