QuizApiClient

Welcome!

Installation

Add this line to your application's Gemfile:

gem 'quiz_api_client'

And then execute:

$ bundle

Or install it yourself as:

$ gem install quiz_api_client

Usage

This client library is used to access quiz_api through Signed Auth, our implementation of signing a JWT with the appropriate scope and resource_id.

Currently, the "services" are organized by resource, following the REST convention of pluralization.

Instantiate the Client

To instantiate a client, you'll need the secret and the host.

client = QuizApiClient::Client.new(
  consumer_key: 'the consumer key normally stored in the quiz_api signed_auth_consumers table',
  host: 'your-quiz-api-host-here.com',
  shared_secret: 'the-api-secret normally stored on the quiz_api account',
  protocol: 'http' # Set this to what you need, ideally it's an environment variable
)

Error Handler

In order to set addition error information in your error handling system, you can set the error_hander property of the config. The list of valid values can be found in the QuizApiClient::Config::ERROR_HANDLERS constant.

Metrics

HTTP Request metrics will now be provided if the setup_metrics method is called. The list of valid values can be found in the QuizApiClient::Config::METRICS_HANDLERS constant. The count and duration metrics will be provided under the namespace provided.

Creation of Tokens

JWTs are created without hitting quiz_api and and they are validated on quiz_api. Tokens are created for a given scope, expiration, and an optional resource_id.

Example, generate a token for building:

client.jwt_service.grant_permission(
  scope: 'quiz.build',
  exp: Time.now.utc.to_i + 60, # some reasonable time, obviously longer is more a security risk
  resource_id: 1)

Calling the API

Example, create a Quiz:

client.quizzes_service.create(
  params: {
    title: 'My quiz'
  },
  token: my_scoped_token
)

Currently Supported Functionality

Quizzes Service

# Create Quiz
client.quizzes_service.create(token:, params:)

# List Quizzes
client.quizzes_service.list(token:, params:)

Quiz Entries Service

# Get Quiz Entries
client.quiz_entries_service.list(
  token: my_scoped_token,
  params: {
    id: quiz_id
  }
)

Quiz Session Service

# Update Quiz Session
client.quiz_session_service.update(
  token: my_scoped_token,
  params: {
    id: quiz_session_id,
    # Other params here
  }
)

Quiz Sessions Service

# Create Quiz Session
client.quiz_sessions_service.create(
  token: my_scoped_token,
  params: {
    quiz_id: quiz_id_to_create_session_under
  }
)

QTI Imports Service

# Create QTI Import
client.qti_imports_service.create(
  token: my_scoped_token,
  params: {
    quiz_id: quiz_id_to_create_import_under,
    qti_import: {
      url: url where QTI Export is stored
    }
  }
)

Item Analyses Service

# List item analyses
client.item_analyses_service.list(
  token: my_scoped_token,
  params: {
    quiz_id: quiz_id_to_list_items_under
  }
)
# get specific item analysis
client.item_analyses_service.get(
  token: my_scoped_token,
  params: {
    quiz_id: quiz_id_to_list_items_under,
    id: item_id_to_get_under
  }
)

Quiz Analyses Service

# get specific item analysis
client.quiz_analyses_service.get(
  token: my_scoped_token,
  params: {
    quiz_id: quiz_id_to_get_analysis
  }
)

Quiz Session Events Service

# list quiz session events
client.quiz_session_events_service.list(
  token: my_scoped_token,
  params: {
    quiz_session_id: quiz_session_id_to_get_events_under
  }
)

Development

After checking out the repo, run bin/setup to install dependencies.

Then, run bundle exec rake spec to run the tests.

You can also run bundle exec rake 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, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.