Class: EdFi::Client

Inherits:
Crapi::Client
  • Object
show all
Defined in:
lib/ed_fi/client.rb,
lib/ed_fi/client/version.rb,
lib/ed_fi/client/response.rb,
lib/ed_fi/client/access_token.rb,
lib/ed_fi/client/errors.rb,
lib/ed_fi/client/proxy.rb,
lib/ed_fi/client/auth.rb

Overview

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.

Defined Under Namespace

Classes: AccessToken, ArgumentError, Auth, Error, Proxy, Response, UnableToAuthenticateError

Constant Summary collapse

VERSION =

The canonical ed_fi_client gem version.

This should only ever be updated immediately before a release; the commit that updates this value should be pushed by the rake release process.

'0.1.0'.freeze
PROFILE_MIME_TYPE =

The "profile" header content-type template.

'application/vnd.ed-fi.%<resource>s.%<profile>s.%<access>s+json'.freeze

Instance Method Summary collapse

Constructor Details

#initialize(base_uri, opts = {}) ⇒ Client

Returns a new instance of Client.

Parameters:

  • 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.

  • opts (Hash) (defaults to: {}) —

    Method options. All options not explicitly listed below are passed on to Crapi::Client.

Options Hash (opts):

  • :profile (String) —

    The profile for which #read and #write will generate headers, if any.

  • :client_id (String) —

    The client id to use for authentication. This is AKA the "api key" / "username".

  • :client_secret (String) —

    The client secret to use for authentication. This is AKA the "api secret" / "password".

Raises:



41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/ed_fi/client.rb', line 41

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

Instance Method Details

#delete(path, headers: {}, query: {}) ⇒ Object

CRUD method: DELETE

headers and query are preprocessed for auth and case conversion, but all parameters are otherwise passed through to Crapi::Proxy#delete.



121
122
123
124
 
# File 'lib/ed_fi/client.rb', line 121

def delete(path, headers: {}, query: {})
  (headers, query) = preprocess(headers, query)
  respond_with super(path, headers: headers, query: query)
end

#get(path, headers: {}, query: {}) ⇒ Object

CRUD method: GET

headers and query are preprocessed for auth and case conversion, but all parameters are otherwise passed through to Crapi::Proxy#get.



131
132
133
134
 
# File 'lib/ed_fi/client.rb', line 131

def get(path, headers: {}, query: {})
  (headers, query) = preprocess(headers, query)
  respond_with super(path, headers: headers, query: query)
end

#patch(path, headers: {}, query: {}, payload: {}) ⇒ Object

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.



141
142
143
144
 
# File 'lib/ed_fi/client.rb', line 141

def patch(path, headers: {}, query: {}, payload: {})
  (headers, query, payload) = preprocess(headers, query, payload)
  respond_with super(path, headers: headers, query: query, payload: payload)
end

#post(path, headers: {}, query: {}, payload: {}) ⇒ Object

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.



151
152
153
154
 
# File 'lib/ed_fi/client.rb', line 151

def post(path, headers: {}, query: {}, payload: {})
  (headers, query, payload) = preprocess(headers, query, payload)
  respond_with super(path, headers: headers, query: query, payload: payload)
end

#profile=(profile) ⇒ Object

Sets the profile to use for #read / #write calls.

Parameters:

  • profile (String, Symbol) —

    The profile for which #read and #write will generate headers.



63
64
65
 
# File 'lib/ed_fi/client.rb', line 63

def profile=(profile)
  @profile = profile&.to_s&.downcase
end

#put(path, headers: {}, query: {}, payload: {}) ⇒ Object

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.



161
162
163
164
 
# File 'lib/ed_fi/client.rb', line 161

def put(path, headers: {}, query: {}, payload: {})
  (headers, query, payload) = preprocess(headers, query, payload)
  respond_with super(path, headers: headers, query: query, payload: payload)
end

#read(resource, as: nil) ⇒ HashWithIndifferentAccess

Returns the header needed to #get a resource with a profile.

Parameters:

  • resource (String, Symbol) —

    The resource to be read.

  • as (String, Symbol) (defaults to: nil) —

    The profile to use. If one has already been set via #initialize or #profile=, this value is optional.

Returns:

  • (HashWithIndifferentAccess) 


82
83
84
85
86
87
 
# File 'lib/ed_fi/client.rb', line 82

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

#v2(period = nil) ⇒ EdFi::Client::Proxy

Convenience proxy generator for v2.0 API access, also addomg the school year you'd like to access, if given.

v2(2017).)

Parameters:

  • period (Integer) (defaults to: nil) —

    The school year to be accessed. (To access the v2.0 API for school year 2017-2018, call

Returns:



179
180
181
182
183
184
185
186
187
188
 
# File 'lib/ed_fi/client.rb', line 179

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

#write(resource, as: nil) ⇒ HashWithIndifferentAccess

Returns the header needed to #delete / #patch / #post / #put a resource with a profile.

Parameters:

  • resource (String, Symbol) —

    The resource to be written.

  • as (String, Symbol) (defaults to: nil) —

    The profile to use. If one has already been set via #initialize or #profile=, this value is optional.

Returns:

  • (HashWithIndifferentAccess) 


106
107
108
109
110
111
 
# File 'lib/ed_fi/client.rb', line 106

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