RubyGems - ed_fi_client - Versions diffs - 0.1.0 - Mend

ed_fi_client 0.1.0

Files changed (47) hide show

checksums.yaml +7 -0
data/.gitignore +11 -0
data/.rspec +3 -0
data/.rubocop.yml +78 -0
data/.ruby-version +1 -0
data/.travis.yml +5 -0
data/.yardopts +1 -0
data/Gemfile +6 -0
data/Gemfile.lock +65 -0
data/LICENSE.txt +21 -0
data/README.md +113 -0
data/Rakefile +6 -0
data/bin/console +14 -0
data/bin/setup +8 -0
data/docs/EdFi.html +127 -0
data/docs/EdFi/Client.html +1204 -0
data/docs/EdFi/Client/AccessToken.html +541 -0
data/docs/EdFi/Client/ArgumentError.html +143 -0
data/docs/EdFi/Client/Auth.html +440 -0
data/docs/EdFi/Client/Error.html +139 -0
data/docs/EdFi/Client/Proxy.html +521 -0
data/docs/EdFi/Client/Response.html +479 -0
data/docs/EdFi/Client/UnableToAuthenticateError.html +145 -0
data/docs/_index.html +203 -0
data/docs/class_list.html +51 -0
data/docs/css/common.css +1 -0
data/docs/css/full_list.css +58 -0
data/docs/css/style.css +499 -0
data/docs/file.README.html +124 -0
data/docs/file_list.html +56 -0
data/docs/frames.html +17 -0
data/docs/index.html +124 -0
data/docs/js/app.js +248 -0
data/docs/js/full_list.js +216 -0
data/docs/js/jquery.js +4 -0
data/docs/method_list.html +235 -0
data/docs/top-level-namespace.html +110 -0
data/ed_fi_client.gemspec +32 -0
data/lib/ed_fi/client.rb +244 -0
data/lib/ed_fi/client/access_token.rb +63 -0
data/lib/ed_fi/client/auth.rb +99 -0
data/lib/ed_fi/client/errors.rb +19 -0
data/lib/ed_fi/client/proxy.rb +65 -0
data/lib/ed_fi/client/response.rb +150 -0
data/lib/ed_fi/client/version.rb +18 -0
data/lib/ed_fi_client.rb +1 -0
metadata +201 -0

data/docs/top-level-namespace.html ADDED Viewed

@@ -0,0 +1,110 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Top Level Namespace
+    &mdash; Documentation by YARD 0.9.12
+</title>
+  <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
+  <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
+<script type="text/javascript" charset="utf-8">
+  pathId = "";
+  relpath = '';
+</script>
+  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+    <a href="_index.html">Index</a> &raquo;
+    <span class="title">Top Level Namespace</span>
+</div>
+        <div id="search">
+    <a class="full_list_link" id="class_list_link"
+        href="class_list.html">
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+</div>
+        <div class="clear"></div>
+      </div>
+      <div id="content"><h1>Top Level Namespace
+</h1>
+<div class="box_info">
+</div>
+<h2>Defined Under Namespace</h2>
+<p class="children">
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="EdFi.html" title="EdFi (module)">EdFi</a></span>
+</p>
+</div>
+      <div id="footer">
+  Generated on Thu May 24 18:35:37 2018 by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.12 (ruby-2.5.1).
+</div>
+    </div>
+  </body>
+</html>

data/ed_fi_client.gemspec ADDED Viewed

@@ -0,0 +1,32 @@
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'ed_fi/client/version'
+Gem::Specification.new do |spec|
+  spec.name          = 'ed_fi_client'
+  spec.version       = EdFi::Client::VERSION
+  spec.authors       = ['Nestor Custodio']
+  spec.email         = ['sakimorix@gmail.com']
+  spec.summary       = 'A simple API wrapper for Ed-Fi ODS access.'
+  spec.homepage      = 'https://www.github.com/nestor-custodio/ed_fi_client'
+  spec.license       = 'MIT'
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'bundler', '~> 1.16'
+  spec.add_development_dependency 'pry', '~> 0.11'
+  spec.add_development_dependency 'pry-byebug', '~> 3.6'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rspec_junit_formatter', '~> 0.3'
+  spec.add_dependency 'activesupport', '~> 5.2.0'
+  spec.add_dependency 'crapi', '~> 0.1'
+end

data/lib/ed_fi/client.rb ADDED Viewed

@@ -0,0 +1,244 @@
+require 'active_support/all'
+require 'crapi'
+require 'ed_fi/client/auth'
+require 'ed_fi/client/errors'
+require 'ed_fi/client/proxy'
+require 'ed_fi/client/response'
+require 'ed_fi/client/version'
+## The main container defined by the **ed_fi_client** gem. Provides a connection mechanism, an
+## authentication mechanism, simple CRUD methods ({#delete} / {#get} / {#patch} / {#post} / {#put}),
+## and proxy generators.
+##
+## All other classes defined in this gem (including gem-specific `::Error` derivatives) are
+## subclasses of {EdFi::Client EdFi::Client}.
+##
+class EdFi::Client < Crapi::Client
+  ## The "profile" header content-type template.
+  PROFILE_MIME_TYPE = 'application/vnd.ed-fi.%<resource>s.%<profile>s.%<access>s+json'.freeze
+  ## @param base_uri [URI, String]
+  ##   The base URI the client should use for determining the host to connect to, whether SSH is
+  ##   applicable, and the path to the target API.
+  ##
+  ## @param opts [Hash]
+  ##   Method options. All options not explicitly listed below are passed on to Crapi::Client.
+  ##
+  ## @option opts [String] :profile
+  ##   The profile for which {EdFi::Client#read} and {EdFi::Client#write} will generate headers, if
+  ##   any.
+  ##
+  ## @option opts [String] :client_id
+  ##   The client id to use for authentication. This is AKA the "api key" / "username".
+  ##
+  ## @option opts [String] :client_secret
+  ##   The client secret to use for authentication. This is AKA the "api secret" / "password".
+  ##
+  ##
+  ## @raise [EdFi::Client::ArgumentError]
+  ##
+  def initialize(base_uri, opts = {})
+    required_opts = %i[client_id client_secret]
+    required_opts.each { |opt| raise ArgumentError, "missing keyword: #{opt}" unless opts.key? opt }
+    super(base_uri, opts)
+    self.profile = opts[:profile]
+    ## Giving the EdFi::Client::Auth instance its own Crapi client lets us do fancy things with the
+    ## API segmenting stuff ...
+    ##
+    auth_client = Crapi::Client.new(base_uri, opts)
+    @auth = EdFi::Client::Auth.new(client: auth_client,
+                                   client_id: opts[:client_id],
+                                   client_secret: opts[:client_secret])
+  end
+  ## Sets the profile to use for {EdFi::Client#read} / {EdFi::Client#write} calls.
+  ##
+  ##
+  ## @param profile [String, Symbol]
+  ##   The profile for which {EdFi::Client#read} and {EdFi::Client#write} will generate headers.
+  ##
+  def profile=(profile)
+    @profile = profile&.to_s&.downcase
+  end
+  ## rubocop:disable Naming/UncommunicativeMethodParamName
+  ## Returns the header needed to {EdFi::Client#get} a resource with a profile.
+  ##
+  ##
+  ## @param resource [String, Symbol]
+  ##   The resource to be read.
+  ##
+  ## @param as [String, Symbol]
+  ##   The profile to use. If one has already been set  via {EdFi::Client#initialize} or
+  ##   {EdFi::Client#profile=}, this value is optional.
+  ##
+  ##
+  ## @return [HashWithIndifferentAccess]
+  ##
+  def read(resource, as: nil)
+    self.profile = as if as.present?
+    mime_type = format(PROFILE_MIME_TYPE, resource: resource, profile: @profile, access: :readable)
+    { 'Accept': mime_type }.with_indifferent_access
+  end
+  ## rubocop:enable Naming/UncommunicativeMethodParamName
+  ## rubocop:disable Naming/UncommunicativeMethodParamName
+  ## Returns the header needed to {EdFi::Client#delete} / {EdFi::Client#patch} / {EdFi::Client#post}
+  ## / {EdFi::Client#put} a resource with a profile.
+  ##
+  ##
+  ## @param resource [String, Symbol]
+  ##   The resource to be written.
+  ##
+  ## @param as [String, Symbol]
+  ##   The profile to use. If one has already been set  via {EdFi::Client#initialize} or
+  ##   {EdFi::Client#profile=}, this value is optional.
+  ##
+  ##
+  ## @return [HashWithIndifferentAccess]
+  ##
+  def write(resource, as: nil)
+    self.profile = as if as.present?
+    mime_type = format(PROFILE_MIME_TYPE, resource: resource, profile: @profile, access: :writable)
+    { 'Content-Type': mime_type }.with_indifferent_access
+  end
+  ## rubocop:enable Naming/UncommunicativeMethodParamName
+  ## CRUD methods ...
+  ## CRUD method: DELETE
+  ##
+  ## *headers* and *query* are preprocessed for auth and case conversion, but all parameters are
+  ## otherwise passed through to Crapi::Proxy#delete.
+  ##
+  def delete(path, headers: {}, query: {})
+    (headers, query) = preprocess(headers, query)
+    respond_with super(path, headers: headers, query: query)
+  end
+  ## CRUD method: GET
+  ##
+  ## *headers* and *query* are preprocessed for auth and case conversion, but all parameters are
+  ## otherwise passed through to Crapi::Proxy#get.
+  ##
+  def get(path, headers: {}, query: {})
+    (headers, query) = preprocess(headers, query)
+    respond_with super(path, headers: headers, query: query)
+  end
+  ## CRUD method: PATCH
+  ##
+  ## *headers*, *query*, and *payload* are preprocessed for auth and case conversion, but all
+  ## parameters are otherwise passed through to Crapi::Proxy#patch.
+  ##
+  def patch(path, headers: {}, query: {}, payload: {})
+    (headers, query, payload) = preprocess(headers, query, payload)
+    respond_with super(path, headers: headers, query: query, payload: payload)
+  end
+  ## CRUD method: POST
+  ##
+  ## *headers*, *query*, and *payload* are preprocessed for auth and case conversion, but all
+  ## parameters are otherwise passed through to Crapi::Proxy#post.
+  ##
+  def post(path, headers: {}, query: {}, payload: {})
+    (headers, query, payload) = preprocess(headers, query, payload)
+    respond_with super(path, headers: headers, query: query, payload: payload)
+  end
+  ## CRUD method: PUT
+  ##
+  ## *headers*, *query*, and *payload* are preprocessed for auth and case conversion, but all
+  ## parameters are otherwise passed through to Crapi::Proxy#put.
+  ##
+  def put(path, headers: {}, query: {}, payload: {})
+    (headers, query, payload) = preprocess(headers, query, payload)
+    respond_with super(path, headers: headers, query: query, payload: payload)
+  end
+  ## API segment proxies ...
+  ## Convenience proxy generator for v2.0 API access, also addomg the school year you'd like to
+  ## access, if given.
+  ##
+  ##
+  ## @param period [Integer]
+  ##   The school year to be accessed. (To access the v2.0 API for school year 2017-2018, call
+  ##  `v2(2017)`.)
+  ##
+  ##
+  ## @return [EdFi::Client::Proxy]
+  ##
+  def v2(period = nil)
+    period = period.to_i
+    @v2 = {} if @v2.nil?
+    @v2[period] ||= begin
+      path = '/api/v2.0'
+      path += "/#{period}" if period.nonzero?
+      EdFi::Client::Proxy.new(add: path, to: self)
+    end
+  end
+  ##
+  private
+  ##
+  ## Generates an auth header, with a valid Bearer token.
+  ##
+  ##
+  ## @return [HashWithIndifferentAccess]
+  ##
+  def auth_header
+    { 'Authorization': "Bearer #{@auth.token}" }.with_indifferent_access
+  end
+  ## Carries out preprocessing for headers, query data, and payload data, returning processed
+  ## *copies* of the given values.
+  ##
+  ##
+  ## @param headers [Hash]
+  ##   The headers to preprocess. A copy of this value is returned with auth headers added, so long
+  ##   as no key conflicts arise.
+  ##
+  ## @param query [Hash]
+  ##   The querystring values to preprocess. Keys will be case-converted where necessary.
+  ##
+  ## @param payload [Hash]
+  ##   The payload values to preprocess. Keys will be case-converted where necessary.
+  ##
+  ##
+  ## @return [(Hash, Hash, Hash)]
+  ##
+  def preprocess(headers, query = nil, payload = nil)
+    payload = payload.as_json if payload.is_a? EdFi::Client::Response
+    headers = auth_header.merge(headers)
+    query = query.deep_transform_keys { |key| key.to_s.camelize(:lower) } if query.is_a? Hash
+    payload = payload.deep_transform_keys { |key| key.to_s.camelize(:lower) } if payload.is_a? Hash
+    [headers, query, payload]
+  end
+  ## Returns an {EdFi::Client::Response EdFi::Client::Response} for the given API resonse value.
+  ##
+  ##
+  ## @param response [Hash, Array]
+  ##   The API response Hash/Array to convert to an {EdFi::Client::Response EdFi::Client::Response}.
+  ##
+  ##
+  ## @return [EdFi::Client::Response]
+  ##
+  def respond_with(response)
+    EdFi::Client::Response.new(response, client: self)
+  end
+end

data/lib/ed_fi/client/access_token.rb ADDED Viewed

@@ -0,0 +1,63 @@
+require 'crapi'
+class EdFi::Client < Crapi::Client
+  ## The {EdFi::Client::AccessToken EdFi::Client::AccessToken} represents an access token, as
+  ## returned by "/oauth/token" calls.
+  ##
+  class AccessToken
+    ## An {EdFi::Client::AccessToken EdFi::Client::AccessToken} can be initiialized with the
+    ## "/oauth/token" response Hash. If given, an additional "issued_at" Time value helps to more
+    ## accurately calculate the token's expiration Time.
+    ##
+    ##
+    ## @param access_token [String]
+    ##   The actual token value to use as the Bearer token in subsequent requests.
+    ##
+    ## @param token_type [String]
+    ##   The token type (e.g. "bearer").
+    ##
+    ## @param issued_at [Time]
+    ##   An optional value denoting the Time at which the token was issued.
+    ##   If unset, defaults to `Time.current`.
+    ##
+    ## @param expires_in [Numeric]
+    ##   The token's lifetime, in seconds.
+    ##
+    def initialize(access_token:, token_type:, issued_at: Time.current, expires_in:)
+      @access_token = access_token.dup
+      @token_type = token_type.dup
+      @issued_at = issued_at.dup
+      @expires_in = expires_in.dup
+    end
+    ## Gives a copy of the token *value*.
+    ##
+    ##
+    ## @return [String]
+    ##
+    def token
+      @access_token.dup
+    end
+    ## Gives the token's *calculated* expiration Time.
+    ##
+    ##
+    ## @return [Time]
+    ##
+    def expires_at
+      return 1.second.ago if @access_token.blank?
+      (@issued_at + @expires_in.seconds)
+    end
+    ## Denotes whether the token is still "valid", per its (calculated) expiration timesstamp. Note
+    ## that a 5-second window is allotted for the request using the token to complete.
+    ##
+    ##
+    ## @return [true,false]
+    ##
+    def valid?
+      safety_window = 5.seconds
+      Time.current <= (expires_at - safety_window)
+    end
+  end
+end