General Usage

Installation

The Zendesk API client can be installed using Rubygems or Bundler.

gem install zendesk_api

Or, add it to your Gemfile

gem "zendesk_api"

and follow normal Bundler installation and execution procedures.

Usage

The result of configuration is an instance of ZendeskAPI::Client which can then be used in two different methods.

One way to use the client is to pass it in as an argument to individual classes.

# doesn't actually send a request, must explicitly call #save
ticket = ZendeskAPI::Ticket.new(client, :id => 1, :priority => "urgent")
# PUT /api/v2/tickets/1.json
ticket.save

# POST /api/v2/tickets.json
ZendeskAPI::Ticket.create(client, :subject => "Test Ticket", :comment => { :value => "This is a test" }, :submitter_id => client.current_user.id, :priority => "urgent")

# GET /api/v2/tickets/1.json
ZendeskAPI::Ticket.find(client, :id => 1)

# DELETE /api/v2/tickets/1.json
ZendeskAPI::Ticket.destroy(client, :id => 1)

Another way is to use the collection methods under client.

# GET /api/v2/tickets.json
client.tickets.first
# GET /api/v2/tickets/1.json
client.tickets.find(:id => 1)
# POST /api/v2/tickets.json
client.tickets.create(:subject => "Test Ticket", :comment => { :value => "This is a test" }, :submitter_id => client.current_user.id, :priority => "urgent")
# DELETE /api/v2/tickets/1.json
client.tickets.destroy(:id => 1)

The methods under ZendeskAPI::Client (such as .tickets) return an instance of ZendeskAPI::Collection a lazy-loaded list of that resource. Actual requests may not be sent until an explicit ZendeskAPI::Collection#fetch, ZendeskAPI::Collection#to_a, or applicable methods such as #each are called.

Resource management

Individual resources can be created, modified, saved, and destroyed.

ticket = client.tickets[0] # ZendeskAPI::Ticket.find(client, :id => 1)
ticket.priority = "urgent"
ticket.attributes # => { "priority" => "urgent", ... }
ticket.save # PUT /api/v2/tickets/1.json => true
ticket.destroy # DELETE /api/v2/tickets/1.json => true

ZendeskAPI::Ticket.new(client, { :priority => "urgent" })
ticket.new_record? # => true
ticket.save # POST /api/v2/tickets.json

Caveats

Resource updating is implemented by sending only the #changed? attributes to the server (see ZendeskAPI::TrackChanges). Unfortunately, this module only hooks into Hash meaning any changes to an Arraynot resulting in a new instance will not be tracked and sent.

zendesk_api_client_rb $ bundle console
> a = ZendeskAPI::Trackie.new(:tags => []).tap(&:clear_changes)
> a.changed?(:tags)
 => false
> a.tags << "my_new_tag"
 => ["my_new_tag"]
> a.changed?(:tags)
 => false
> a.tags += %w{my_other_tag}
 => ["my_new_tag", "my_other_tag"]
> a.changed?(:tags)
 => true

Please keep in mind that the valid properties for your objects can be found in the API reference and you need to use _id fields for associations, you can't pass association objects as you do in ActiveRecord.