Knowledge Base: API Overview

Hoptoad provides easy access to all your data via an XML-based, RESTful API.

There are also a number of Alternative Plugins, Widgets, and Extras that Hoptoad users have built.

There is one prerequisite to using the API: you must have an auth_token. When logged in, you can find your auth_token at the "My Profile" page.

Accessing the API using Ruby

If you are using Ruby, then you can use ActiveResource to write a client to easily connect to the API. Here is what it'd look like:

# code at http://gist.github.com/3350
# tests at http://gist.github.com/3354

class Hoptoad < ActiveResource::Base
  self.site = "http://your_account.hoptoadapp.com"

  class << self
    @@auth_token = 'your_auth_token'

    def find(*arguments)
      arguments = append_auth_token_to_params(*arguments)
      super(*arguments)
    end

    def append_auth_token_to_params(*arguments)
      opts = arguments.last.is_a?(Hash) ? arguments.pop : {}
      opts = opts.has_key?(:params) ? opts : opts.merge(:params => {}) 
      opts[:params] = opts[:params].merge(:auth_token => @@auth_token)
      arguments << opts
      arguments
    end
  end
end

class Error < Hoptoad  
end

# Errors are paginated. You get 30 at a time.

@errors = Error.find :all
@errors = Error.find :all, :params => { :page => 2 }

Accessing the API Directly

The API is a normal Rails REST service, and while Ruby is our preferred language, you can use any language you want to query the API.

• To get the XML for the 30 most recently active errors:
  http://your_account.hoptoadapp.com/errors.xml?auth_token=TOKEN
• To get the XML for the next 30 most recently active errors:
  http://your_account.hoptoadapp.com/errors.xml?auth_token=TOKEN&page=2
• To get the XML for a specific error:
  http://your_account.hoptoadapp.com/errors/ERROR-ID.xml?auth_token=TOKEN
• To set a particular error as resolved, use a PUT. For example, with RestClient: RestClient.put("http://thoughtbot.hoptoad.local/errors/#{error_id}?auth_token=#{auth_token}", :group => { :resolved => true})

When getting multiple errors at once, the environment, backtrace, session, and request information will not be returned along with the errors. To view this additional information request the xml for the individual error.

Here is the XML for a typical error

<?xml version="1.0" encoding="UTF-8"?>
<group>
  <action>create</action>
  <controller>session</controller>
  <created-at type="datetime">2008-07-09T20:06:44-07:00</created-at>
  <error-class>NoMethodError</error-class>
  <error-message>NoMethodError: undefined method `password' for nil:NilClass</error-message>

  <file>[RAILS_ROOT]/app/models/user.rb</file>
  <id type="integer">5529</id>
  <last-notice-at type="datetime">2008-07-31T04:21:52-07:00</last-notice-at>
  <last-notice-id type="integer">203799</last-notice-id>
  <line-number type="integer">186</line-number>
  <notices-count type="integer">30</notices-count>

  <project-id type="integer">2</project-id>
  <rails-env>production</rails-env>
  <updated-at type="datetime">2008-07-31T04:21:52-07:00</updated-at>
  <visible type="boolean">true</visible>
</group>

Submitting Errors to Hoptoad

In order to submit errors to Hoptoad, you can either use the hoptoad_notifier plugin for Rails, or access the API directly. For information about the notifier, API, see http://help.hoptoadapp.com/faqs/api-2/notifier-api-v2.