Exceptional Publish API

The Exceptional Publish API accepts error information which is then processed and made available on exceptional.io.

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:in `gonuts'", 
"/actionpack-2.3.2/lib/action_controller/base.rb:1322:in `send'", 
"/actionpack-2.3.2/lib/action_controller/base.rb:1322:in `perform_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:in `perform_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:in `ms'", 
"/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:in `ms'"],
       "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 6 entries 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.exceptional.io

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

POST http://api.exceptional.io/api/errors?api_key=YOUR_API_KEY&protocol_version=6
Thats all you should need to pass your own error data to exceptional!