RubyGems - ed_fi_client - Versions diffs - 0.1.0 - Mend

ed_fi_client 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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