# QuizApiClient

Welcome!

## Installation

Add this line to your application's Gemfile:

```ruby
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.

```ruby
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
)
```

### 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:
```ruby
client.quiz_service.token(
  scope: client.quiz_service.scope_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:
```ruby
client.quiz_service.create(
  params: {
    title: 'My quiz'
  }
```

### Currently Supported Functionality

#### Quiz Service

**Tokens**
```ruby
# Generate Build token
client.quiz_service.token(
  scope: client.quiz_service.scope_build,
  exp: some_expiration,
  resource_id: quiz_id_here
)
```

#### Quizzes Service

**Tokens**
```ruby
# Generate token: Create Quiz
client.quizzes_service.token(
  scope: client.quizzes_service.scope_create,
  exp: some_expiration
)

# List Quizzes
client.quizzes_service.token(
  scope: client.quizzes_service.scope_list,
  exp: some_expiration
)
```

**API Calls**
```ruby
# Create Quiz
client.quizzes_service.create(params:)

# List Quizzes
client.quizzes_service.list(params:)
```

#### Quiz Session Service

**Tokens**
```ruby
# Generate token: Grade Quiz Session
client.quiz_session_service.token(
  scope: client.quiz_session_service.scope_grade,
  exp: some_expiration,
  resource_id: quiz_session_id
)

# Generate token: Take Quiz Session
client.quiz_session_service.token(
  scope: client.quiz_session_service.scope_take,
  exp: some_expiration,
  resource_id: quiz_session_id
)

# Generate token: Update Quiz Session
client.quiz_session_service.token(
  scope: client.quiz_session_service.scope_update,
  exp: some_expiration,
  resource_id: quiz_session_id
)
```

**API Calls**
```ruby
# Update Quiz Session
client.quiz_session_service.update(
  params: {
    id: quiz_session_id,
    # Other params here
  }
)
```

#### Quiz Sessions Service

**Tokens**
```ruby
# Generate token: Create Quiz Session
client.quiz_sessions_service.token(
  scope: client.quiz_sessions_service.scope_create,
  exp: some_expiration
)
```

**API Calls**
```ruby
# Create Quiz Session
client.quiz_sessions_service.create(
  params: {
    quiz_id: quiz_id_to_create_session_under
  }
)
```

#### QTI Imports Service

**Tokens**
```ruby
# Generate token: Create Qti Import
client.qti_imports_service.token(
  scope: client.quizzes_service.scope_create,
  exp: some_expiration
)
```

**API Calls**
```ruby
# Create QTI Import
client.qti_imports_service.create(
  params: {
    quiz_id: quiz_id_to_create_import_under,
    qti_import: {
      url: url where QTI Export is stored
    }
  }
)
```

#### Item Analyses Service

**Tokens**
```ruby
# Generate token: Fetch Item Analyses
client.item_analyses_service.token(
  scope: client.item_analyses_service.scope_analysis,
  exp: some_expiration
)
```

**API Calls**
```ruby
# List item analyses
client.item_analyses_service.list(
  params: {
    quiz_id: quiz_id_to_list_items_under
  }
)
# get specific item analysis
client.item_analyses_service.get(
  params: {
    quiz_id: quiz_id_to_list_items_under,
    id: item_id_to_get_under
  }
)
```

#### Quiz Analyses Service

**Tokens**
```ruby
# Generate token: Fetch Quiz Analyses
client.quiz_analyses_service.token(
  scope: client.quiz_analyses_service.scope_analysis,
  exp: some_expiration
)
```

**API Calls**
```ruby
# get specific item analysis
client.quiz_analyses_service.get(
  params: {
    quiz_id: quiz_id_to_get_analysis
  }
)
```

#### Quiz Session Events Service

**Tokens**
```ruby
# Generate token: Fetch Quiz Session Events
client.quiz_session_events_service.token(
  scope: client.quiz_session_events_service.scope_list,
  exp: some_expiration
)
```

**API Calls**
```ruby
# list quiz session events
client.quiz_session_events_service.list(
  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 `rake spec` to run the tests.

You can also run `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](https://rubygems.org).