canvas-api 0.5

data/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2013 Instructure
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,92 @@
+# Canvas API
+
+This ruby library is to make it easier to use the
+[Canvas API](http://api.instructure.com).
+
+## Installation
+This is packaged as the `canvas-api` rubygem, so you can just add the dependency to
+your Gemfile or install the gem on your system:
+
+    gem install canvas-api
+
+To require the library in your project:
+
+    require 'canvas-api'
+
+## Usage
+
+### OAuth Dance
+
+Before you can make API calls you need an access token on behalf of the current user.
+In order to get an access token you'll need to do the OAuth dance (and for that you'll
+need a client_id and secret. Talk to the Canvas admin about getting these values):
+
+```ruby
+canvas = Canvas::API.new(:host => "https://canvas.example.com", :client_id => 123, :secret => "abcdef")
+url = canvas.oauth_url("https://my.site/oauth_success")
+# => "https://canvas.example.com/login/oauth2/auth?client_id=123&response_type=code&redirect_uri=http%3A%2F%2Fmy.site%2Foauth_success
+redirect to(url)
+```
+
+And then when the browser redirects to oauth_success:
+
+```ruby
+canvas = Canvas::API.new(:host => "https://canvas.example.com", :client_id => 123, :secret => "abcdef")
+code = params['code']
+canvas.retrieve_access_token(code, 'https://my.site/oauth_success') # this callback_url must match the one provided in the first step
+# => {access_token: "qwert"}
+```
+### General API Calls
+
+Once you've got an access token for a user you should save it (securely!) for future use. To use the API call:
+
+```ruby
+canvas = Canvas::API.new(:host => "https://canvas.example.com", :token => "qwert")
+canvas.get("/api/v1/users/self/profile")
+# => {id: 90210, name: "Annie Wilson", ... }
+```
+
+### Pagination
+
+API endpoints that return lists are often paginated, meaning they will only return the first X results
+(where X depends on the endpoint and, possibly, the per_page parameter you optionally set). To get more
+results you'll need to make additional API calls:
+
+```ruby
+canvas = Canvas::API.new(:host => "https://canvas.example.com", :token => "qwert")
+list = canvas.get("/api/v1/calendar_events?all_events=true")
+list.length
+# => 50
+list.more?
+# => true (if there's another page of results)
+list.next_page!
+# => [...] (returns the next page of results)
+list.length
+# => 100 (also concatenates the results on to the previous list, if that's more convenient)
+list.next_page!
+# => [...]
+list.length
+# => 150
+```
+
+### Additional Utilities
+
+There are also some helper methods that can make some of the other tricky parts of the Canvas API a little more approachable.
+
+#### File Uploads
+
+TODO...
+
+#### SIS ID Encoding
+
+In addition to regular IDs, Canvas supports [SIS IDs](https://canvas.instructure.com/doc/api/file.object_ids.html) defined
+by other systems. Sometimes these IDs contain non-standard characters, which can cause problems when
+trying to use them via the API. In those cases you can do the following:
+
+```ruby
+sis_course_id = canvas.encode_id("sis_course_id", "r#-789")
+# => "hex:sis_course_id:72232d373839"
+canvas.get("/api/v1/courses/#{sis_course_id}/enrollments")
+# => [...]
+```
+

data/lib/canvas-api.rb

@@ -0,0 +1,183 @@
+require 'uri'
+require 'cgi'
+require 'net/http'
+require 'json'
+
+module Canvas
+  class API
+    def initialize(args={}) 
+      @host = args[:host] && args[:host].to_s
+      @token = args[:token] && args[:token].to_s
+      @client_id = args[:client_id] && args[:client_id].to_s
+      @secret = args[:secret] && args[:secret].to_s
+      raise "host required" unless @host
+      raise "invalid host, protocol required" unless @host.match(/^http/)
+      raise "invalid host" unless @host.match(/^https?:\/\/[^\/]+$/)
+      raise "token or client_id required" if !@token && !@client_id
+      raise "secret required for client_id configuration" if @client_id && !@secret
+    end
+  
+    attr_accessor :host
+    attr_accessor :token
+    attr_accessor :client_id
+  
+    def masquerade_as(user_id)
+      @as_user_id = user_id && user_id.to_s
+    end
+  
+    def stop_masquerading
+      @as_user_id = nil
+    end
+  
+    def self.encode_id(prefix, id)
+      return nil unless prefix && id
+      "hex:#{prefix}:" + id.to_s.unpack("H*")[0]
+    end
+    
+    def encode_id(prefix, id)
+      Canvas::API.encode_id(prefix, id)
+    end
+  
+    def oauth_url(callback_url, scopes="")
+      raise "client_id required for oauth flow" unless @client_id
+      raise "secret required for oauth flow" unless @secret
+      raise "callback_url required" unless callback_url
+      raise "invalid callback_url" unless (URI.parse(callback_url) rescue nil)
+      scopes ||= ""
+      scopes = scopes.length > 0 ? "&scopes=#{CGI.escape(scopes)}" : ""
+      "#{@host}/login/oauth2/auth?client_id=#{@client_id}&response_type=code&redirect_uri=#{CGI.escape(callback_url)}#{scopes}"
+    end
+  
+    def login_url(callback_url)
+      oauth_url(callback_url, "/auth/userinfo")
+    end
+  
+    def retrieve_access_token(code, callback_url)
+      raise "client_id required for oauth flow" unless @client_id
+      raise "secret required for oauth flow" unless @secret
+      raise "code required" unless code
+      raise "callback_url required" unless callback_url
+      raise "invalid callback_url" unless (URI.parse(callback_url) rescue nil)
+      @token = "ignore"
+      res = post("/login/oauth2/token", :client_id => @client_id, :redirect_uri => callback_url, :client_secret => @secret, :code => code)
+      if res['access_token']
+        @token = res['access_token']
+      end
+      res
+    end
+  
+    def logout
+      !!delete("/login/oauth2/token")['logged_out']
+    end
+  
+    def validate_call(endpoint)
+      raise "token required for api calls" unless @token
+      raise "missing host" unless @host
+      raise "missing endpoint" unless endpoint
+      raise "missing leading slash on endpoint" unless endpoint.match(/^\//)
+      raise "invalid endpoint" unless endpoint.match(/^\/api\/v\d+\//) unless @token == 'ignore'
+      raise "invalid endpoint" unless (URI.parse(endpoint) rescue nil)
+    end
+  
+    def generate_uri(endpoint)
+      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
+      @uri = URI.parse(@host + endpoint)
+      @http = Net::HTTP.new(@uri.host, @uri.port)
+      @http.use_ssl = @uri.scheme == 'https'
+      @uri
+    end
+  
+    def retrieve_response(request)
+      request['User-Agent'] = "CanvasAPI Ruby"
+      begin
+        response = @http.request(request)
+      rescue Timeout::Error => e
+        raise ApiError.new("request timed out")
+      end
+      raise ApiError.new("unexpected redirect to #{response.location}") if response.code.to_s.match(/3\d\d/)
+      json = JSON.parse(response.body) rescue {'error' => 'invalid JSON'}
+      if !json.is_a?(Array)
+        raise ApiError.new(json['error']) if json['error']
+        if !response.code.to_s.match(/2\d\d/)
+          json['message'] ||= "unexpected error"
+          raise ApiError.new("#{json['status']} #{json['message']}") 
+        end
+      else
+        json = ResultSet.new(self, json)
+        if response['link']
+          json.link = response['link']
+          json.next_endpoint = response['link'].split(/,/).detect{|rel| rel.match(/rel="next"/) }.split(/;/).first.strip[1..-2].sub(/https?:\/\/[^\/]+/, '') rescue nil
+        end
+      end
+      json
+    end
+    
+    # Semi-hack so I can write better specs
+    def get_request(endpoint)
+      Net::HTTP::Get.new(@uri.request_uri)
+    end
+  
+    def get(endpoint)
+      generate_uri(endpoint)
+      request = get_request(endpoint)
+      retrieve_response(request)
+    end
+  
+    def delete(endpoint)
+      generate_uri(endpoint)
+      request = Net::HTTP::Delete.new(@uri.request_uri)
+      retrieve_response(request)
+    end
+  
+    def put(endpoint, params={})
+      generate_uri(endpoint)
+      request = Net::HTTP::Put.new(@uri.request_uri)
+      request.set_form_data(params)
+      retrieve_response(request)
+    end
+  
+    def post(endpoint, params={})
+      generate_uri(endpoint)
+      request = Net::HTTP::Post.new(@uri.request_uri)
+      request.set_form_data(params)
+      retrieve_response(request)
+    end
+  
+    def upload_file_from_local
+      # TODO
+    end
+  
+    def upload_file_from_url
+      # TODO
+    end
+  end
+
+  class ApiError < StandardError
+  end
+
+  class ResultSet < Array
+    def initialize(api, arr)
+      @api = api
+      super(arr)
+    end
+    attr_accessor :next_endpoint
+    attr_accessor :link
+    
+    def more?
+      !!next_endpoint
+    end
+    
+    def next_page!
+      ResultSet.new(@api, []) unless next_endpoint
+      more = @api.get(next_endpoint)
+      concat(more)
+      @next_endpoint = more.next_endpoint
+      @link = more.link
+      more
+    end
+  end
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: canvas-api
+version: !ruby/object:Gem::Version
+  version: '0.5'
+  prerelease: 
+platform: ruby
+authors:
+- Instructure
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ruby-debug
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email: 
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE
+files:
+- lib/canvas-api.rb
+- LICENSE
+- README.md
+- Changelog
+homepage: http://github.com/whitmer/canvas-api
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Ruby library for accessing the Canvas API
+test_files: []
+has_rdoc: