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. We also have a tutorial using Python as an example.

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.

If you are looking to send notifications to Hoptoad (perhaps for your own custom notifier), instead of reading data, you'll want to read up on the Notifier API.

A note about SSL

If your plan supports SSL, you must access the API over an HTTPS connection. Standard HTTP requests to the API for these accounts will return an "HTTP 403 Forbidden" status.

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
• By default, errors which are marked as resolved are not included. To include these, add a parameter include_resolved=true to your HTTP request.
• 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:

http://your_account.hoptoadapp.com/errors/1000.xml

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>

To access a paginated list of notices for this error, request the notices index nested under the error:

http://your_account.hoptoadapp.com/errors/1000/notices.xml?page=1

To get detailed information on a specific notice:

http://your_account.hoptoadapp.com/errors/1000/notices/3456789.xml

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.