canvas-api 0.5 → 0.6

data/README.md

@@ -46,6 +46,29 @@ canvas.get("/api/v1/users/self/profile")
 # => {id: 90210, name: "Annie Wilson", ... }
 ```
 
+For POST and PUT requests the second parameter is the form parameters to append, either as a hash or
+an array of arrays:
+
+```ruby
+canvas = Canvas::API.new(:host => "https://canvas.example.com", :token => "qwert")
+canvas.put("/api/v1/users/self", {'user[name]' => 'Dixon Wilson', 'user[short_name]' => 'Dixon'})
+# => {id: 90210, name: "Dixon Wilson", ... }
+canvas.put("/api/v1/users/self", {'user' => {'name' => 'Dixon Wilson', 'short_name' => 'Dixon'}}) # this is synonymous with the previous call
+# => {id: 90210, name: "Dixon Wilson", ... }
+canvas.put("/api/v1/users/self", [['user[name]', 'Dixon Wilson'],['user[short_name]', 'Dixon']]) # this is synonymous with the previous call
+# => {id: 90210, name: "Dixon Wilson", ... }
+```
+
+On GET requests you can either append query parameters to the actual path or as a hashed second argument:
+
+```ruby
+canvas = Canvas::API.new(:host => "https://canvas.example.com", :token => "qwert")
+canvas.get("/api/v1/users/self/enrollments?type[]=TeacherEnrollment&type[]=TaEnrollment")
+# => [{id: 1234, course_id: 5678, ... }, {id: 2345, course_id: 6789, ...}]
+canvas.get("/api/v1/users/self/enrollments", {'type' => ['TeacherEnrollment', 'TaEnrollment']}) # this is synonymous with the previous call
+# => [{id: 1234, course_id: 5678, ... }, {id: 2345, course_id: 6789, ...}]
+```
+
 ### Pagination
 
 API endpoints that return lists are often paginated, meaning they will only return the first X results
@@ -75,7 +98,66 @@ There are also some helper methods that can make some of the other tricky parts
 
 #### File Uploads
 
-TODO...
+Uploading files ia typically a multi-step process. There are three different ways to upload
+files.
+
+Upload a file from the local file system:
+
+
+```ruby
+canvas = Canvas::API.new(:host => "https://canvas.example.com", :token => "qwert")
+canvas.upload_file_from_local("/api/v1/users/self/files", File.open("/path/to/file.jpg"), :content_type => "image/jpeg")
+# => {id: 1, display_name: "file.jpg", ... }
+```
+
+Upload a file synchronously from a remote URL:
+
+```ruby
+canvas = Canvas::API.new(:host => "https://canvas.example.com", :token => "qwert")
+canvas.upload_file_from_url("/api/v1/users/self/files", :name => "image.jpg", :size => 12345, :url => "http://www.example.com/image.jpg")
+# => {id: 1, display_name: "image.jpg", ... }
+```
+
+Upload a file asynchronouysly from a remote URL:
+
+```ruby
+canvas = Canvas::API.new(:host => "https://canvas.example.com", :token => "qwert")
+status_url = canvas.upload_file_from_url("/api/v1/users/self/files", :asynch => true, :name => "image.jpg", :size => 12345, :url => "http://www.example.com/image.jpg")
+# => "/api/v1/file_status/url"
+canvas.get(status_url)
+# => {upload_status: "pending"}
+canvas.get(status_url)
+# => {upload_status: "ready", attachment: {id: 1, display_name: "image.jpg", ... } }
+```
+
+```ruby
+canvas = Canvas::API.new(:host => "https://canvas.example.com", :token => "qwert")
+status_url = canvas.upload_file_from_url("/api/v1/users/self/files", :asynch => true, :name => "image.jpg", :size => 12345, :url => "http://www.example.com/image.jpg")
+# => "/api/v1/file_status/url"
+canvas.get(status_url)
+# => {upload_status: "errored", message: "Invalid response code, expected 200 got 404"}
+```
+
+For any of these upload types you can optionally provide additional configuration parameters if
+the upload endpoint is to an area of Canvas that supports folders (user files, course files, etc.)
+
+```ruby
+canvas = Canvas::API.new(:host => "https://canvas.example.com", :token => "qwert")
+#
+# upload the file to a known folder with id 1234
+canvas.upload_file_from_url("/api/v1/users/self/files", :parent_folder_id => 1234, :name => "image.jpg", :size => 12345, :url => "http://www.example.com/image.jpg")
+# => {id: 1, display_name: "image.jpg", ... }
+#
+# upload the file to a folder with the path "/friends"
+canvas.upload_file_from_url("/api/v1/users/self/files", :parent_folder_path => "/friends", :name => "image.jpg", :size => 12345, :url => "http://www.example.com/image.jpg")
+# => {id: 1, display_name: "image.jpg", ... }
+#
+# rename this file instead of overwriting a file with the same name (overwrite is the default)
+canvas.upload_file_from_url("/api/v1/users/self/files", :on_duplicate => "rename", :name => "image.jpg", :size => 12345, :url => "http://www.example.com/image.jpg")
+# => {id: 1, display_name: "image.jpg", ... }
+```
+
+
 
 #### SIS ID Encoding
 

data/lib/canvas-api.rb

@@ -1,8 +1,10 @@
 require 'uri'
 require 'cgi'
 require 'net/http'
+require 'net/http/post/multipart'
 require 'json'
 
+
 module Canvas
   class API
     def initialize(args={}) 
@@ -79,12 +81,22 @@ module Canvas
       raise "invalid endpoint" unless (URI.parse(endpoint) rescue nil)
     end
   
-    def generate_uri(endpoint)
+    def generate_uri(endpoint, params=nil)
       validate_call(endpoint)
       unless @token == "ignore"
         endpoint += (endpoint.match(/\?/) ? "&" : "?") + "access_token=" + @token
         endpoint += "&as_user_id=" + @as_user_id.to_s if @as_user_id
       end
+      (params || {}).each do |key, value|
+        if value.is_a?(Array)
+          key = key + "[]" unless key.match(/\[\]/)
+          value.each do |val|
+            endpoint += (endpoint.match(/\?/) ? "&" : "?") + "#{CGI.escape(key.to_s)}=#{CGI.escape(val.to_s)}"
+          end
+        else
+          endpoint += (endpoint.match(/\?/) ? "&" : "?") + "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
+        end
+      end
       @uri = URI.parse(@host + endpoint)
       @http = Net::HTTP.new(@uri.host, @uri.port)
       @http.use_ssl = @uri.scheme == 'https'
@@ -121,8 +133,8 @@ module Canvas
       Net::HTTP::Get.new(@uri.request_uri)
     end
   
-    def get(endpoint)
-      generate_uri(endpoint)
+    def get(endpoint, params=nil)
+      generate_uri(endpoint, params)
       request = get_request(endpoint)
       retrieve_response(request)
     end
@@ -134,30 +146,108 @@ module Canvas
     end
   
     def put(endpoint, params={})
-      generate_uri(endpoint)
+      generate_uri(endpoint, params['query_parameters'] || params[:query_parameters])
       request = Net::HTTP::Put.new(@uri.request_uri)
-      request.set_form_data(params)
+      request.set_form_data(clean_params(params))
       retrieve_response(request)
     end
   
     def post(endpoint, params={})
-      generate_uri(endpoint)
+      generate_uri(endpoint, params['query_parameters'] || params[:query_parameters])
       request = Net::HTTP::Post.new(@uri.request_uri)
-      request.set_form_data(params)
+      request.set_form_data(clean_params(params))
       retrieve_response(request)
     end
+    
+    def clean_params(params, prefix=nil)
+      params ||= {}
+      return params if params.is_a?(Array)
+      return nil unless params.is_a?(Hash)
+      params.delete(:query_parameters)
+      res = []
+      params.each do |key, val|
+        if val.is_a?(Array)
+          raise "No support for nested array parameters currently"
+        elsif val.is_a?(Hash)
+          res += clean_params(val, prefix ? (prefix + "[" + key.to_s + "]") : key.to_s)
+        else
+          if prefix
+            res << [prefix + "[" + key.to_s + "]", val.to_s]
+          else
+            res << [key.to_s, val.to_s]
+          end
+        end
+      end
+      res
+    end
   
-    def upload_file_from_local
-      # TODO
+    def upload_file_from_local(endpoint, file, opts={})
+      raise "Missing File object" unless file.is_a?(File)
+      params = {
+        :size => file.size,
+        :name => opts[:name] || opts['name'] || File.basename(file.path),
+        :content_type => opts[:content_type] || opts['content_type'] || "application/octet-stream",
+        :parent_folder_id => opts[:parent_folder_id] || opts['parent_folder_id'],
+        :parent_folder_path => opts[:parent_folder_path] || opts['parent_folder_path'],
+        :on_duplicate => opts[:on_duplicate] || opts['on_duplicate']
+      }
+      res = post(endpoint, params)
+      if !res['upload_url']
+        raise ApiError.new("Unexpected error: #{res['message'] || 'no upload URL returned'}")
+      end
+      status_url = multipart_upload(res['upload_url'], res['upload_params'], params, file)
+      status_path = "/" + status_url.split(/\//, 4)[-1]
+      res = get(status_path)
+      res
+    end
+    
+    def multipart_upload(url, upload_params, params, file)
+      uri = URI.parse(url)
+      @multipart_args = upload_params.merge({})
+      @multipart_args['file'] = UploadIO.new(file, params[:content_type], params[:name])
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      req = Net::HTTP::Post::Multipart.new(uri.path, @multipart_args)
+      res = http.start do |stream_http|
+        stream_http.request(req)
+      end
+      raise ApiError.new("Unexpected error: #{res.body}") if !res['Location']
+      res['Location']
     end
   
-    def upload_file_from_url
-      # TODO
+    def upload_file_from_url(endpoint, opts)
+      asynch = opts.delete('asynch') || opts.delete(:asynch)
+      ['url', 'name', 'size'].each do |k|
+        raise "Missing value: #{k}" unless opts[k.to_s] || opts[k.to_sym]
+      end
+
+      res = post(endpoint, opts)
+      status_url = res['status_url']
+      if !status_url
+        raise ApiError.new("Unexpected error: #{res['message'] || 'no status URL returned'}")
+      end
+      status_path = "/" + status_url.split(/\//, 4)[-1]
+      if asynch
+        return status_path
+      else
+        attachment = nil
+        while !attachment
+          res = get(status_path)
+          if res['upload_status'] == 'errored'
+            raise ApiError.new(res['message'])
+          elsif !res['upload_status']
+            raise ApiError.new("Unexpected response")
+          end
+          status_path = res['status_path'] if res['status_path']
+          attachment = res['attachment']
+          sleep (defined?(SLEEP_TIME) ? SLEEP_TIME : 5) unless attachment
+        end
+        attachment
+      end
     end
   end
 
-  class ApiError < StandardError
-  end
+  class ApiError < StandardError; end
 
   class ResultSet < Array
     def initialize(api, arr)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: canvas-api
 version: !ruby/object:Gem::Version
-  version: '0.5'
+  version: '0.6'
   prerelease: 
 platform: ruby
 authors: