assembly-client 0.7.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f92b2d669534abd9b9b26e3c787fdab63df57e07
+  data.tar.gz: d0e1e73ff72e633dd56bd78e8c76a6e5f0995c3a
+SHA512:
+  metadata.gz: 3c9f002e27c138da49ffe704109552895bf5dd476faaa74a91e29368c88e589fdbd84fdc37bf294094cc34927a6d77eaf3d530b8f5e5d0f1038ae5d8f15c8fdf
+  data.tar.gz: ec13e8836d87a79d326382d57a35ee6159a898afd846ef9e57737b044d7dc98b35dcdaa547284ba935f08bd582e5cc3548d72a0c9618d79d60fa140083e4e812

data/.gitignore

@@ -0,0 +1,19 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# Non-generic RVM files
+.ruby-gemset
+ 
+# Ignore IntelliJ files
+.generators
+.rakeTasks
+*.iml
+.idea
+

data/.ruby-version

@@ -0,0 +1 @@
+2.4.1

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+ruby File.read('.ruby-version').strip
+
+# Specify your gem's dependencies in assembly.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,9 @@
+clearing :on
+
+guard :minitest do
+  # watch(%r{^test/(.*)\/?(.*)_test\.rb$})
+  # watch(%r{^lib/(.*/)?([^/]+)\.rb$})           { |m| "test/#{m[1]}#{m[2]}_test.rb" }
+  # watch(%r{^lib/assembly/(.*/)?([^/]+)\.rb$})  { |m| "test/#{m[1]}#{m[2]}_test.rb" }
+  # watch(%r{^test/test_helper\.rb$})            { 'test' }
+  watch(%r{(.+)\.rb}) { 'test' }
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Project Assembly
+
+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,56 @@
+# Assembly
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'assembly', github: 'assembly-edu/assembly-client-ruby'
+
+```
+
+## Usage
+
+Some examples of how to pull information from the Assembly Platform API using the client Gem.
+
+```ruby
+Assembly.configure do |config|
+  config.host  = 'https://api-sandbox.assembly.education/'       # For sandbox testing. Use https://api.assembly.education/ for production
+  config.token = 'my_oauth_access_token'
+
+  # You do not need this configuration for a quick play with the API. It's only needed for the refresh token OAuth flow.
+  config.auth_host     = 'https://platform-sandbox.assembly.education/'  # For sandbox testing. Use https://platform.assembly.education/ for production
+  config.refresh_token = 'my_oauth_refresh_token'
+  config.client_id     = 'my_app_id'
+  config.client_secret = 'my_app_secret'
+end
+
+api = Assembly.client
+
+# Fetch all teaching groups (you may know these as classes) for the mathematics subject code.
+maths_groups = api.teaching_groups.all(subject_code: 'MA')
+
+maths_groups.each do |g|
+  puts "Group Name: #{g.name}"
+end
+
+# Fetch all the students for this teaching group.
+students = maths_groups.first.students(per_page: 100)
+
+students.each do |student|
+  puts "#{student.last_name}, #{student.first_name} (#{student.year_code})"
+end
+
+# ...or fetch all students filtered by year code/year group
+api.students.all(year_code: '7')
+
+```
+
+## Development
+
+Run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test

data/assembly-client.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'assembly/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "assembly-client"
+  spec.version       = Assembly::VERSION
+  spec.authors       = ["Assembly Education"]
+  spec.email         = ["developers@assembly.education"]
+
+  spec.summary       = %q{Ruby client library for the Assembly Platform}
+  spec.homepage      = "http://platform.assembly.education"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "faraday",            "~> 0.13.1"
+  spec.add_dependency "faraday_middleware", "~> 0.12.2"
+
+  spec.add_development_dependency "bundler",            "~> 1.15"
+  spec.add_development_dependency "rake",               "~> 12.1"
+  spec.add_development_dependency "mocha",              "~> 1.3"
+  spec.add_development_dependency "webmock",            "~> 3.0"
+  spec.add_development_dependency "guard",              "~> 2.14"
+  spec.add_development_dependency "guard-minitest",     "~> 2.4"
+  spec.add_development_dependency "minitest-reporters", "~> 1.1"
+end

data/bin/console

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "assembly"
+
+Assembly.configure do |config|
+  config.token = '3z1678w3qstvanq6x1r8f0b2mcjefjv'
+  config.host  = 'http://localhost:3000'
+end
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/assembly.rb

@@ -0,0 +1,64 @@
+require "assembly/version"
+
+require 'json'
+require "ostruct"
+
+require "faraday"
+require "faraday_middleware"
+
+require 'assembly/faraday_middleware/assembly_oauth2'
+require 'assembly/util'
+require 'assembly/config'
+require 'assembly/client'
+require 'assembly/actions/read'
+require 'assembly/actions/list'
+require 'assembly/actions/create'
+require 'assembly/actions/update'
+require 'assembly/actions/delete'
+require 'assembly/model'
+require 'assembly/api_model'
+require 'assembly/resource'
+require 'assembly/models/aspect'
+require 'assembly/models/assessment'
+require 'assembly/models/attendance'
+require 'assembly/models/exclusion'
+require 'assembly/models/facet'
+require 'assembly/models/year_group'
+require 'assembly/models/list'
+require 'assembly/models/result'
+require 'assembly/models/academic_year'
+require 'assembly/models/assessment_point'
+require 'assembly/models/calendar_event'
+require 'assembly/models/contact'
+require 'assembly/models/grade'
+require 'assembly/models/grade_set'
+require 'assembly/models/registration_group'
+require 'assembly/models/school_detail'
+require 'assembly/models/staff_member'
+require 'assembly/models/student'
+require 'assembly/models/subject'
+require 'assembly/models/teaching_group'
+
+module Assembly
+  @config = Config.new
+
+  class << self
+    attr_accessor :config
+
+    def configure(options=nil)
+      @config.merge(options) if options.is_a?(Hash)
+      yield(config) if block_given?
+    end
+
+    # nil - standard client
+    # Config object - new client with config
+    # Hash - new client with config extended by hash
+    def client(options=nil)
+      @client ||= Client.new
+      return @client if options.nil?
+      return options if options.is_a?(Client)
+      client_config = options.is_a?(Config) ? options : @config.copy_with_overrides(options)
+      Client.new(client_config)
+    end
+  end
+end

data/lib/assembly/actions/create.rb

@@ -0,0 +1,16 @@
+module Assembly
+  module Actions
+    module Create
+      module ClassMethods
+        def create(args, client=Assembly.client)
+          response = client.post(path, args)
+          Util.build(response, client)
+        end
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/assembly/actions/delete.rb

@@ -0,0 +1,21 @@
+module Assembly
+  module Actions
+    module Delete
+      module ClassMethods
+        def delete(id, client=Assembly.client)
+          response = client.delete("#{path}/#{id}")
+          true
+        end
+      end
+
+      def delete
+        client.delete(path)
+        true
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/assembly/actions/list.rb

@@ -0,0 +1,33 @@
+module Assembly
+  module Actions
+    module List
+      module ClassMethods
+        def list(params, client=Assembly.client)
+          response = client.get(path, params)
+          Util.build(response, client)
+        end
+
+        def all(params, client=Assembly.client)
+          params.delete(:page)
+          params.delete(:per_page)
+          results = []
+          page = 1
+          while page
+            ret = list({page: page, per_page: 100}.merge(params), client)
+            results += ret.data
+            page = ret.next_page
+          end
+          results
+        end
+
+        def total_count(params={}, client=Assembly.client)
+          list({per_page: 1}.merge(params), client).total_count
+        end
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/assembly/actions/read.rb

@@ -0,0 +1,18 @@
+module Assembly
+  module Actions
+    module Read
+      module ClassMethods
+        def fetch(id, params={}, client=Assembly.client)
+          raise ArgumentError.new("an id must be provided to fetch a record") if id.nil? || id.to_s.empty?
+          response = client.get("#{path}/#{id}", params)
+          Util.build(response, client)
+        end
+        alias_method :find, :fetch
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/assembly/actions/update.rb

@@ -0,0 +1,22 @@
+module Assembly
+  module Actions
+    module Update
+      module ClassMethods
+        def update(id, params, client=Assembly.client)
+          response = client.put("#{path}/#{id}", params)
+          Util.build(response)
+        end
+      end
+
+      def update(params={})
+        response = client.put(path, dirty_params.merge(params))
+        self.update_from(response)
+      end
+      alias_method :save, :update
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/assembly/api_model.rb

@@ -0,0 +1,25 @@
+module Assembly
+  class ApiModel < Model
+    def path
+      "#{self.class.path}/#{id}"
+    end
+
+    def self.path
+      "/#{Util.underscore(self.class_name)}s"
+    end
+
+    protected
+
+    def pages(path, params)
+      results = []
+      page = 1
+      while page
+        response = client.get(path, {page: page, per_page: 100}.merge(params))
+        ret = Util.build(response, client)
+        results += ret.data
+        page = ret.next_page
+      end
+      results
+    end
+  end
+end

data/lib/assembly/client.rb

@@ -0,0 +1,227 @@
+module Assembly
+  class Client
+    attr_reader :config
+
+    def initialize(config=Assembly.config)
+      @config           = config
+      @on_token_refresh = nil
+      build_api_adapter
+    end
+
+    def get(url, params={})
+      if_modified_since = params.delete(:since)
+      headers = {}
+      headers.merge!({ 'IF_MODIFIED_SINCE': if_modified_since }) if if_modified_since
+
+      response = @api.get(url, params, headers)
+      ok       = check_errors(response)
+      if ok
+        response.body
+      else
+        get(url, params)
+      end
+    end
+
+    def post(url, params={})
+      response = @api.post url, params.to_json
+      check_errors(response)
+      response.body
+    end
+
+    def put(url, params={})
+      response = @api.put url, params.to_json
+      check_errors(response)
+      response.body
+    end
+
+    def delete(url)
+      response = @api.delete url
+      check_errors(response)
+      response.status == 200
+    end
+
+    def academic_years
+      Assembly::AcademicYearResource.new(self)
+    end
+
+    def assessments
+      Assembly::AssessmentResource.new(self)
+    end
+
+    def assessment_points
+      Assembly::AssessmentPointResource.new(self)
+    end
+
+    def aspects
+      Assembly::AspectResource.new(self)
+    end
+
+    def calendar_events
+      Assembly::CalendarEventResource.new(self)
+    end
+
+    def contacts
+      Assembly::ContactResource.new(self)
+    end
+
+    def grade_sets
+      Assembly::GradeSetResource.new(self)
+    end
+
+    def registration_groups
+      Assembly::RegistrationGroupResource.new(self)
+    end
+
+    def results
+      Assembly::ResultResource.new(self)
+    end
+
+    def school_details
+      Assembly::SchoolDetailResource.new(self)
+    end
+
+    def facets
+      Assembly::FacetResource.new(self)
+    end
+
+    def staff_members
+      Assembly::StaffMemberResource.new(self)
+    end
+
+    def students
+      Assembly::StudentResource.new(self)
+    end
+
+    def subjects
+      Assembly::SubjectResource.new(self)
+    end
+
+    def teaching_groups
+      Assembly::TeachingGroupResource.new(self)
+    end
+
+    def attendances
+      Assembly::AttendanceResource.new(self)
+    end
+
+    def exclusions
+      Assembly::ExclusionResource.new(self)
+    end
+
+    def year_groups
+      Assembly::YearGroupResource.new(self)
+    end
+
+    def on_token_refresh(&blk)
+      @on_token_refresh = blk
+    end
+
+    def refresh_token!
+      return false unless config.client_id && config.client_secret && config.refresh_token
+      refresh_api = Faraday.new(:url => config.auth_host) do |faraday|
+        faraday.request :url_encoded
+        faraday.response :json
+        faraday.adapter Faraday.default_adapter
+      end
+      refresh_api.headers[:accept]        = "application/vnd.assembly+json; version=#{config.api_version}"
+      refresh_api.headers[:authorization] = refresh_api.basic_auth(config.client_id, config.client_secret)
+
+      response = refresh_api.post('/oauth/token', {
+        grant_type:    'refresh_token',
+        refresh_token: config.refresh_token
+      })
+      return false unless check_errors(response)
+      config.token = response.body[:access_token]
+      build_api_adapter
+      @on_token_refresh.call(response.body) if @on_token_refresh
+      true
+    end
+
+    private
+
+    def check_errors(response)
+      status = response.status.to_i
+      case status
+        when 401
+          handle_unauthorized_response(response)
+          return false
+        when 404
+          raise Assembly::NotFoundError.new(response)
+        when 422
+          raise Assembly::ValidationError.new(response)
+        when 429
+          raise Assembly::TooManyRequestsError.new(response)
+        when 500
+          raise Assembly::ServerError.new(response)
+      end
+      true
+    end
+
+    def handle_unauthorized_response(response)
+      if response.body[:error] != 'invalid_token'
+        raise Assembly::UnauthorizedError.new(response)
+      end
+      raise Assembly::UnauthorizedError.new(response) unless refresh_token!
+    end
+
+    def build_api_adapter
+      @api = Faraday.new(:url => config.host) do |faraday|
+        faraday.request :json
+        faraday.request :assembly_oauth2, config.token
+        faraday.response :json
+        faraday.adapter Faraday.default_adapter
+      end
+      @api.headers[:accept] = "application/vnd.assembly+json; version=#{config.api_version}"
+    end
+  end
+
+  class ServerError < StandardError
+    def initialize(response)
+      @response = response
+    end
+
+    def status
+      @response.status
+    end
+
+    def message
+      body = @response.body
+      if body && body.length > 0
+        body[:message]
+      else
+        "No Error Message - Server response body was empty."
+      end
+    end
+
+    def to_s
+      "[#{status}] #{message}"
+    end
+  end
+
+  class TooManyRequestsError < ServerError
+  end
+
+  class NotFoundError < ServerError
+  end
+
+  class UnauthorizedError < ServerError
+  end
+
+  class ValidationError < ServerError
+    def errors
+      @response.body[:errors]
+    end
+
+    def to_s
+      "#{super} - #{errors.inspect}"
+    end
+  end
+end
+
+module FaradayMiddleware
+  class ParseJson
+    define_parser do |body|
+      ::JSON.parse(body, symbolize_names: true) unless body.strip.empty?
+    end
+  end
+end