clever / clever-ruby

Clever Ruby library

Notice

This repo is no longer maintained by Clever. We provide the Swagger definitions at https://github.com/Clever/swagger-api.

clever-ruby

Clever - the Ruby gem for the Clever API

The Clever API

This SDK is automatically generated by the Swagger Codegen project:

• API version: 2.0.0
• Package version: 2.0.1
• Build package: io.swagger.codegen.languages.RubyClientCodegen

Installation

Build a gem

To build the Ruby code into a gem:

gem build clever-ruby.gemspec

Then either install the gem locally:

gem install ./clever-ruby-2.0.1.gem

(for development, run gem install --dev ./clever-ruby-2.0.1.gem to install the development dependencies)

or publish the gem to a gem hosting service, e.g. RubyGems.

Finally add this to the Gemfile:

gem 'clever-ruby', '~> 2.0.1'

Install from Git

If the Ruby gem is hosted at a git repository: https://github.com/GIT_USER_ID/GIT_REPO_ID, then add the following in the Gemfile:

gem 'clever-ruby', :git => 'https://github.com/GIT_USER_ID/GIT_REPO_ID.git'

Include the Ruby code directly

Include the Ruby code directly using -I as follows:

ruby -Ilib script.rb

Getting Started

Please follow the installation procedure and then run the following code:

# Load the gem
require 'clever-ruby'

# Setup authorization
Clever.configure do |config|
  # Configure OAuth2 access token for authorization: oauth
  config.access_token = 'YOUR ACCESS TOKEN'
end

api_instance = Clever::DataApi.new

id = "id_example" # String | 


begin
  result = api_instance.get_contact(id)
  p result
rescue Clever::ApiError => e
  puts "Exception when calling DataApi->get_contact: #{e}"
end

Documentation for API Endpoints

All URIs are relative to https://api.clever.com/v2.0

Class	Method	HTTP request	Description
Clever::DataApi	get_contact	GET /contacts/{id}
Clever::DataApi	get_contacts	GET /contacts
Clever::DataApi	get_contacts_for_student	GET /students/{id}/contacts
Clever::DataApi	get_course	GET /courses/{id}
Clever::DataApi	get_course_for_section	GET /sections/{id}/course
Clever::DataApi	get_courses	GET /courses
Clever::DataApi	get_district	GET /districts/{id}
Clever::DataApi	get_district_admin	GET /district_admins/{id}
Clever::DataApi	get_district_admins	GET /district_admins
Clever::DataApi	get_district_for_contact	GET /contacts/{id}/district
Clever::DataApi	get_district_for_course	GET /courses/{id}/district
Clever::DataApi	get_district_for_district_admin	GET /district_admins/{id}/district
Clever::DataApi	get_district_for_school	GET /schools/{id}/district
Clever::DataApi	get_district_for_school_admin	GET /school_admins/{id}/district
Clever::DataApi	get_district_for_section	GET /sections/{id}/district
Clever::DataApi	get_district_for_student	GET /students/{id}/district
Clever::DataApi	get_district_for_teacher	GET /teachers/{id}/district
Clever::DataApi	get_district_for_term	GET /terms/{id}/district
Clever::DataApi	get_districts	GET /districts
Clever::DataApi	get_school	GET /schools/{id}
Clever::DataApi	get_school_admin	GET /school_admins/{id}
Clever::DataApi	get_school_admins	GET /school_admins
Clever::DataApi	get_school_for_section	GET /sections/{id}/school
Clever::DataApi	get_school_for_student	GET /students/{id}/school
Clever::DataApi	get_school_for_teacher	GET /teachers/{id}/school
Clever::DataApi	get_schools	GET /schools
Clever::DataApi	get_schools_for_school_admin	GET /school_admins/{id}/schools
Clever::DataApi	get_schools_for_student	GET /students/{id}/schools
Clever::DataApi	get_schools_for_teacher	GET /teachers/{id}/schools
Clever::DataApi	get_section	GET /sections/{id}
Clever::DataApi	get_sections	GET /sections
Clever::DataApi	get_sections_for_course	GET /courses/{id}/sections
Clever::DataApi	get_sections_for_school	GET /schools/{id}/sections
Clever::DataApi	get_sections_for_student	GET /students/{id}/sections
Clever::DataApi	get_sections_for_teacher	GET /teachers/{id}/sections
Clever::DataApi	get_sections_for_term	GET /terms/{id}/sections
Clever::DataApi	get_student	GET /students/{id}
Clever::DataApi	get_students	GET /students
Clever::DataApi	get_students_for_contact	GET /contacts/{id}/students
Clever::DataApi	get_students_for_school	GET /schools/{id}/students
Clever::DataApi	get_students_for_section	GET /sections/{id}/students
Clever::DataApi	get_students_for_teacher	GET /teachers/{id}/students
Clever::DataApi	get_teacher	GET /teachers/{id}
Clever::DataApi	get_teacher_for_section	GET /sections/{id}/teacher
Clever::DataApi	get_teachers	GET /teachers
Clever::DataApi	get_teachers_for_school	GET /schools/{id}/teachers
Clever::DataApi	get_teachers_for_section	GET /sections/{id}/teachers
Clever::DataApi	get_teachers_for_student	GET /students/{id}/teachers
Clever::DataApi	get_term	GET /terms/{id}
Clever::DataApi	get_term_for_section	GET /sections/{id}/term
Clever::DataApi	get_terms	GET /terms
Clever::EventsApi	get_event	GET /events/{id}
Clever::EventsApi	get_events	GET /events

Documentation for Models

• Clever::BadRequest
• Clever::Contact
• Clever::ContactObject
• Clever::ContactResponse
• Clever::ContactsResponse
• Clever::Course
• Clever::CourseObject
• Clever::CourseResponse
• Clever::CoursesResponse
• Clever::Credentials
• Clever::District
• Clever::DistrictAdmin
• Clever::DistrictAdminObject
• Clever::DistrictAdminResponse
• Clever::DistrictAdminsResponse
• Clever::DistrictObject
• Clever::DistrictResponse
• Clever::DistrictsResponse
• Clever::Event
• Clever::EventResponse
• Clever::EventsResponse
• Clever::InternalError
• Clever::Location
• Clever::Name
• Clever::NotFound
• Clever::Principal
• Clever::School
• Clever::SchoolAdmin
• Clever::SchoolAdminObject
• Clever::SchoolAdminResponse
• Clever::SchoolAdminsResponse
• Clever::SchoolObject
• Clever::SchoolResponse
• Clever::SchoolsResponse
• Clever::Section
• Clever::SectionObject
• Clever::SectionResponse
• Clever::SectionsResponse
• Clever::Student
• Clever::StudentObject
• Clever::StudentResponse
• Clever::StudentsResponse
• Clever::Teacher
• Clever::TeacherObject
• Clever::TeacherResponse
• Clever::TeachersResponse
• Clever::Term
• Clever::TermObject
• Clever::TermResponse
• Clever::TermsResponse
• Clever::ContactsCreated
• Clever::ContactsDeleted
• Clever::ContactsUpdated
• Clever::CoursesCreated
• Clever::CoursesDeleted
• Clever::CoursesUpdated
• Clever::DistrictadminsCreated
• Clever::DistrictadminsDeleted
• Clever::DistrictadminsUpdated
• Clever::DistrictsCreated
• Clever::DistrictsDeleted
• Clever::DistrictsUpdated
• Clever::SchooladminsCreated
• Clever::SchooladminsDeleted
• Clever::SchooladminsUpdated
• Clever::SchoolsCreated
• Clever::SchoolsDeleted
• Clever::SchoolsUpdated
• Clever::SectionsCreated
• Clever::SectionsDeleted
• Clever::SectionsUpdated
• Clever::StudentsCreated
• Clever::StudentsDeleted
• Clever::StudentsUpdated
• Clever::TeachersCreated
• Clever::TeachersDeleted
• Clever::TeachersUpdated
• Clever::TermsCreated
• Clever::TermsDeleted
• Clever::TermsUpdated

Documentation for Authorization

oauth

• Type: OAuth
• Flow: accessCode
• Authorization URL: https://clever.com/oauth/authorize
• Scopes: N/A

Previous Versions

The current client support v2.0 of the API. For v1.2 please use:

• https://rubygems.org/gems/clever-ruby/versions/1.2.4
• https://github.com/Clever/clever-ruby/tree/v1.2.4

Updating the Library

1. Git clone swagger-codegen (https://github.com/swagger-api/swagger-codegen)

2. Git clone Clever's swagger-api repo (https://github.com/Clever/swagger-api)

3. Run this command in the swagger-codegen repo

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -i $PATH_TO_SWAGGER_API_REPO/v2.0-client.yml -l ruby -o $PATH_TO_THIS_REPO --additional-properties gemVersion=$VERSION

4. Run make build to copy over the override files

Publishing

Signup to rubygems.org if you don't already have an account, and ask one of the gem owners to add you as an owner. You'll be prompted to log in from the command line when you push the gem, if you aren't already logged in.

To add a new owner, you need to be an owner, then run this command: gem owner clever-ruby -a <emailaddress>

1. Update CHANGELOG.md
2. gem build clever-ruby.gemspec
3. gem push clever-ruby-X.Y.Z.gem

clever-ruby's Issues

Problem with connecting to the API v1.1 using 0.14.0

Hello there,

Two days ago (07/11) we started having issues with getting an events feed using ver. 0.13.2 (also confirmed to be a problem in 0.14.0). The same code used to work until then.

The error message is the following:

Clever::APIError: Invalid response object from API: "Cannot GET //v1.1/events?starting_after=some-id-that-I-replaced-here" (HTTP response code was 404)
from /home/vagrant/.rvm/gems/ruby-2.1.8/gems/clever-ruby-0.14.0/lib/clever-ruby.rb:294:in `rescue in handle_api_error'

It looks like for some of the requests the gem constructs the path with double slash in the beginning. I'm not sure what have changed on the backend side, but apparently it no longer supports the requests constructed by this gem.

v2.1 API release

Hello,

Is there a timeline for a library release to support the current v2.1 API?

https://dev.clever.com/docs/upgrading-version

Thanks!

Improve means of regenerating test data

Swapping in and out OAuth tokens is ugly and confusing.

TODO: link to current instructions in README once #63 is merged.

API version 3.0 support

https://dev.clever.com/docs

Duplicated method

I was browsing through the code and I think this method is duplicated here.

TravisCI

Would you be interested in having travisci.org set up for running the tests? It's free for open source projects and I've set it up before, so I'm more than happy to but I wanted to check that you were interested first.

Testing github --> jira hook

There's nothing to see here

Bug In Events API: event's type and id missing

Event's type and id metadata missing for the events like SutdentsCreated and StudentsDeleted

School data parsing issue

#98 data parsing failed when "" passed high_grade value.
This event was received from Clever Events API:

{
      "data": {
        "type": "schools.updated",
        "data": {
          "object": {
            "last_modified": "2017-08-09T02:12:56.190Z",
            "nces_id": "470455001816",
            "district": "57a0b1d6def84101000000d8",
            "phone": "[phone]",
            "mdr_number": "1234568",
            "high_grade": "",
            "created": "2016-08-11T11:46:56.767Z",
            "name": "Carroll-Oakland Elementary",
            "school_number": "005",
            "low_grade": "",
            "sis_id": "005",
            "location": {
              "address": "4664 Huners Point PK",
              "city": "Lebanon",
              "state": "TN",
              "zip": "37087"
            },
            "id": "57ac65b02eaddb2064000016"
          },
          "previous_attributes": {
            "low_grade": "",
            "high_grade": ""
          }
        },
        "created": "2017-08-09T02:16:28.224Z",
        "id": "598a70777c09dc346c8e4939"
      },
      "uri": "/v1.2/events/598a70777c09dc346c8e4939"
    }

As you may notice low_grade and high_grade fields are set to "", after parsing such event to clever-ruby it causing following exception:

expected no Exception, got #<ArgumentError: invalid value for 'high_grade', must be one of ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "PreKindergarten", "Kindergarten", "PostGraduate", "Other"].> with backtrace:
  # ./lib/clever-ruby/models/school.rb:204:in `high_grade='
  # ./lib/clever-ruby/models/school.rb:266:in `block in build_from_hash'
  # ./lib/clever-ruby/models/school.rb:258:in `each_pair'

No API resource for StudentContact, but Clever has StudentContact events

Clever added StudentContact events to their event stream, but clever-ruby has no idea how to handle these new events because their isn't a APIResource defined for it yet.

API get_contacts_for_students is always returning blank

Whereas when try to fetch the specific parent via get_contact(contact_id) it rightly returns the data.

Suggested Ruby Version?

Hello,

I'm attempting to use this gem and get the following errors when attempting to make a connection:

/Users/user/.rvm/gems/ruby-2.7.2/gems/clever-ruby-2.0.2/lib/clever-ruby/api_client.rb:292: warning: URI.escape is obsolete
/Users/user/.rvm/gems/ruby-2.7.2/gems/ethon-0.12.0/lib/ethon/easy/operations.rb:29: [BUG] Segmentation fault at 0x000000016ef22a00
ruby 2.7.2p137 (2020-10-01 revision 5445e04352) [arm64-darwin20]```

And then I get a huge crash report.  

Add ability to use multiple tokens

Since we use global state to store a token, we can't use multiple tokens. #65 solves this issue. Breaking change.

`get_events` and `get_events_with_http_info` fail for invalid state

I am trying to fetch information for some districts for an ongoing events sync, and am getting the following exception:

ArgumentError: invalid value for 'state', must be one of ["running", "pending", "error", "paused"].

I can make the API call successfully in the API Explorer, so I think this might be a failure when the state is validated while building a districts.updated response. I can see that some districts appear to have had SIS sync issues where they had or have a state of success, which doesn't fit the four types named there, which then causes a validation error.

Here's one of the events I suspect is causing the problem, I've redacted technical details but am happy to share in a private channel:

{
      "data": {
        "type": "districts.updated",
        "data": {
          "object": {
            "last_sync": "2018-09-17T04:57:10.690Z",
            "pause_start": "2018-05-30",
            "launch_date": "2018-04-16",
            "mdr_number": "[redacted]",
            "nces_id": "[redacted]",
            "pause_end": "2018-08-01",
            "name": "[redacted]",
            "state": "success",
            "sis_type": "skyward-api",
            "error": "",
            "id": "[redacted]"
          },
          "previous_attributes": {
            "error": "The data in your most recent sync has changed significantly.  To prevent unintended loss of data, we have not processed this sync.  Please review the \"Action Required: Clever Sync on Hold\" email to resolve this hold.",
            "state": "pending"
          }
        },
        "created": "2018-09-19T19:37:18.800Z",
        "id": "[redacted]"
      },
      "uri": "/v2.0/events/[redacted]"
    },

Don't use global Clever object

Right now methods are called against Clever rather than an instance of Clever. As a result configuration changes in one place can impact it elsewhere, making testability a bit harder, usage of the library less flexible, and leaking the Clever object globally. Require an instance of Clever rather than referring to it statically.

Relax json gem requirement

The JSON gem carries with it native C extensions, that require a compiler toolchain be present on any machine that installs it.

Ruby carries the following JSON gem versions with the distribution by default:

JSON 1.4.2 with 1.9.2 - https://github.com/ruby/ruby/blob/ruby_1_9_2/ext/json/lib/json/version.rb
JSON 1.5.5 with 1.9.3 - https://github.com/ruby/ruby/blob/ruby_1_9_3/ext/json/lib/json/version.rb
JSON 1.7.7 with 2.0.0 series - https://github.com/ruby/ruby/blob/ruby_2_0_0/ext/json/lib/json/version.rb
JSON 1.8.1 with 2.1.0 - through 2.1.7 - https://github.com/ruby/ruby/blob/v2_1_7/ext/json/lib/json/version.rb
JSON 1.8.1 with 2.2.0 - through 2.2.3 - https://github.com/ruby/ruby/blob/v2_2_3/ext/json/lib/json/version.rb
JSON 2.1.0 with 2.5.1
https://github.com/ruby/ruby/blob/v2_5_1/ext/json/lib/json/version.rb

I believe that the way that the json gem dep is being specified in the gemspec file could be relaxed with no ill effects. The way it is currently forces people running newer ruby versions to install an older version of a gem which is now part of the standard lib.

I would suggest removing this dep all together as it is only necessary to support older ruby versions 1.8.* which are not being widely deployed anymore. The other option would be to make the version specification just >= 1.8.

NoMethodError for `linked_resources` in clever_object.rb:215

We recently started encountering an exception being thrown from within clever-ruby.

NoMethodErrorapp/importers/clever/clever_updater.rb:60
undefined method `linked_resources' for Clever::CleverObject:Class

This is actually occurring at this point in the gem:

gems/clever-ruby-0.13.0/lib/clever-ruby/clever_object.rb:215 block (2 levels) in add_accessors

The full stack trace, sans our code, is:

    gems/clever-ruby-0.13.0/lib/clever-ruby/clever_object.rb:215 block (2 levels) in add_accessors
    /usr/local/rvm/rubies/ruby-2.1.7/lib/ruby/2.1.0/set.rb:263 each_key
    /usr/local/rvm/rubies/ruby-2.1.7/lib/ruby/2.1.0/set.rb:263 each
    gems/clever-ruby-0.13.0/lib/clever-ruby/clever_object.rb:213 block in add_accessors
    gems/clever-ruby-0.13.0/lib/clever-ruby/clever_object.rb:212 instance_eval
    gems/clever-ruby-0.13.0/lib/clever-ruby/clever_object.rb:212 add_accessors
    gems/clever-ruby-0.13.0/lib/clever-ruby/clever_object.rb:64 block in refresh_from
    gems/clever-ruby-0.13.0/lib/clever-ruby/clever_object.rb:62 instance_eval
    gems/clever-ruby-0.13.0/lib/clever-ruby/clever_object.rb:62 refresh_from
    gems/clever-ruby-0.13.0/lib/clever-ruby/clever_object.rb:29 construct_from
    gems/clever-ruby-0.13.0/lib/clever-ruby/event.rb:24 object

I presume this is from an event type that is not handled by this gem -- specifically, in event.rb:22, klass is being set to CleverObject by default. This would explain this issue.

I'll open a pull request that changes this default to APIResource.

support ActiveRecord-like pagination

e.g. http://guides.rubyonrails.org/active_record_querying.html#retrieving-multiple-objects-in-batches.

cc @samstrasser @carols10cents

Associated <Resource(s)>Response Types Do Not Include Paging or Links Attributes

When a resource's associated Response type (StudentResponse, TeacherResponse, etc) is returned from a DataAPI method, the paging and link data are not included as attributes in the deserialized response object. This can be fixed by extending a Response type and overriding the .attributes and .swagger_types methods. Originally identified by @jedspurg

Here's an example of a workaround:

  class SectionsResponse
    attr_accessor :data, :paging, :links

    def self.attribute_map
      {
        :'data'   => :'data',
        :'paging' => :'paging',
        :'links'  => :'links'
      }
    end

    def self.swagger_types
      {
        :'data'   => :'Array<SectionResponse>',
        :'paging' => :Object,
        :'links'  => :Object
      }
    end
  end

Move ActiveSupport to dev dep rather than runtime dep

Having active support 4.1.5 as a runtime dep makes this gem incompatible with any app running Rails < 4.1. I could also not figure out why is this gem a dep at all but I may have missed the it when looking at the code.

Pass authentication information along to Event#object

There is an issue in the clever gem where authentication information is not provided to clever objects returned from events. IE, if you do:

x = event.object

Any subsequent action with x that hits the clever API will fail.

@TheJefe fixed the same problem somewhere else a while ago:

e7b012b

This issue ends up manifesting itself in our code base in really weird ways.
In order to work around it, we have the clever object from an Event, and then we re-fetch it since the first one doesn't have the correct authentication.

OAuth and '/me' support

I am surprised that there is no support here for the '/me' request and maybe also the code/token OAuth request flow. I can easily make these requests separately in my app but it seems like these would be desirable features for this gem.

I might be able to submit a PR for this but I am wondering if there is some reason this is not being supported and whether such a PR might be accepted.

District_admins functionality

@carols10cents do you plan on implementing this? You had an implementation in the earlier PR—don't want to duplicate your work!

Remove API key functionality

It is deprecated. breaking change.

Remove inflector dependency

Would allow us to remove activesupport dependency, which will make using this application with Rails easier without additional maintenance needs.

Plan: Since there are a small number of finite resources ever used in this application, just hardcode plural and singular forms into the classes themselves. Inflector is overkill.

API version 2.1 support

https://dev.clever.com/docs/new-in-api-v21

push to rubygems.org

It says in your docs that it's a live gem, but sadly it's not.

gem install clever-ruby

$ gem install clever-ruby
ERROR:  Could not find a valid gem 'clever-ruby' (>= 0) in any repository
ERROR:  Possible alternatives: getclever-ruby, amee-ruby, collmex-ruby, cube-ruby, evil-ruby

I saw a few closed tickets regarding making this a gem, but can we at least get a 0.0.1 of it? Is it close enough?

ELL_Status as an Optional Attribute

Within the /lib/clever-ruby/student.rb file the optional_attributes array is missing the ell_status attribute.

Clever Event Subclasses - NameError: uninitialized constant Clever::SchoolsCreated::CleverAPI

It looks like a namespace changed recently occurred and the subclasses of Event were missed.

The _deserialize method of each Event subclass (i.e., SchoolsCreated) still reference CleverAPI. This needs to change to Clever. Better yet, the subclasses don't really need to override this method. As far as I can tell, they add no new functionality and the parent class of Event is properly referencing Clever instead of CleverAPI.

Not clear which methods will make API requests and which won't

With the new linked resources methods, it's not always clear when you have a CleverObject and call methods on it which methods will be doing HTTP calls to the Clever API and which will not.

This is important since we want to minimize the amount of network traffic and avoid it if we don't need it.

Our use case is that, when we do an import from Clever, we create all the objects and then go back and associate them once they exist. Previously, calling, for example, section.students would return the array of student ids associated with that section-- which is all we need when we're associating the two anyway. In the new version of the gem, this fires API requests to get all the data for the students.

We're currently working around this by changing these types of places from section.students to section[:students]. This is kind of confusing, though, since we can ask for other attributes on section using methods and that doesn't make an API call, like section.grade. This requires vigilance to remember what is an attribute and what is an association.

To further muddy the waters, calling event.object seems like it WOULD make an API call, but it does not, as far as I can tell.

I'm not sure exactly what the right solution here is. Maybe define methods for the associated resources that are, e.g., section.student_ids that wouldn't have the name collision that #students and [:students] has. Maybe making the API calling methods have a name like fetch_students. Or close this issue if this doesn't seem like a problem to you, I would also accept that response :)