Publish API

Exceptional Publish API

The Exceptional Publish API accepts error information which is then processed and made available on exceptional.io. Currently, client implementations exist for:

This document will help anyone wishing to develop an exceptional client for other platforms.

JSON Document

The core of the API is a suitably structured JSON document. This document is processed by the Exceptional publish API.
{ "request": { "session": { "session_variable_1": "Session 1 Variable Value", "session_variable_2": "Session 2 Variable Value" }, "remote_ip": "127.0.0.1", "parameters": { "action": "gonuts", "controller": "spike" }, "action": "gonuts", "url": "http://localhost/spike/gonuts", "request_method": "get", "controller": "SpikeController", "headers": { "Version": "HTTP/1.1", "User-Agent": "Mozilla/5.0", "Accept-Encoding": "gzip,deflate", "Keep-Alive": "300", "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8", "Accept-Charset": "ISO-8859-1,utf-8;q=0.7,*;q=0.7", "Accept-Language": "en-us,en;q=0.5", "Connection": "keep-alive", "Host": "myapp.com" } }, "application_environment": { "framework": "rails", "env": { "MANPATH": "/usr/local/git/man:/opt/local/share/man", "SHELL": "/bin/bash", "DISPLAY": "/tmp/launch-SYxDj8/:0", "CVSEDITOR": "mate -w", "LANG": "en_IE.UTF-8", "PWD": "/var/www/myapp", "PATH": "/opt/local/bin:/usr/local/git/bin:/opt/local/bin" }, "language": "ruby", "language_version": "1.8.7 p72 2008-08-11 i686-darwin9", "application_root_directory": "/var/www/myapp" }, "exception": { "occurred_at": "2010-10-29T10:48:54+01:00", "message": "NoMethodError: undefined method horse!' for nil:NilClass", "backtrace": [ "/Users/wal/work/myapp/app/controllers/spike_controller.rb:16:ingonuts'", "/actionpack-2.3.2/lib/action_controller/base.rb:1322:in send'", "/actionpack-2.3.2/lib/action_controller/base.rb:1322:inperform_action_without_filters'", "/actionpack-2.3.2/lib/action_controller/filters.rb:617:in call_filters'", "/actionpack-2.3.2/lib/action_controller/filters.rb:610:inperform_action_without_benchmark'", "/actionpack-2.3.2/lib/action_controller/benchmarking.rb:68:in perform_action_without_rescue'", "/activesupport-2.3.2/lib/active_support/core_ext/benchmark.rb:17:inms'", "/ruby/1.8/benchmark.rb:308:in realtime'", "/ruby/gems/1.8/gems/activesupport-2.3.2/lib/active_support/core_ext/benchmark.rb:17:inms'"], "exception_class": "RuntimeError" }, "client": { "name": "getexceptional-rails-plugin", "version": "0.2.0", "protocol_version": 6 } }

Mandatory Fields

The more information from above that can be provided, the more exceptional features that will be available, but at a minimum the following 6 properties are required for processing:

exception/backtrace

A JSON Array of strings representing the backtrace where the error occurred

exception/exception_class

This string represents the name of the class within which the error occurred

exception/message

The error details string for the error

exception/occurred_at

The time the error occurred at in ISO 8601 format (e.g '2010-10-29T10:48:54+01:00')

application_environment/application_root_directory

The local(client) filesystem location of the project

application_environment/env

A hash containing key value pairs about the applications environment (this can be empty)

Compression

Once the document above is prepared, it must be compressed using gzip (for protocol version 6) or ZLib compression (for protocol version 5). Protocols 5 and 6 are identical except for the compression format.

POST'ing to api.getexceptional.com

Once compressed, the document needs to be posted to the exceptional api. You will need your API_KEY to post this:

POST http://api.getexceptional.com/api/errors?api_key=YOUR_API_KEY&protocol_version=6

Thats all you should need to pass your own error data to exceptional!