New Hoptoad Notification API

[Joe Ferris]

Hi,

We're working on a new notification API for Hoptoad! Here are our
current goals:

* Easier to understand for notifier authors
* Easier to use in other frameworks/languages
* Only support one format (we currently support 4)
* More explicit
* Easier to validate
* Better documentation

Our current preference for a format is XML, because:
* It has more parsers and generators (especially in other languages
than Ruby)
* It's easy to validate
* Its validation documents can be distributed

We have an example of what we think an XML request should like for the
new API: http://gist.github.com/158180

None of this is currently implemented or set in stone, so if you have
ideas to improve this document, or if you have a compelling reason to
use a different format, please let us know.

If we do go with XML, our plan is develop either a DTD or XSD schema
that we'll use to validate incoming documents. This will provide
useful feedback to notifier authors when something is wrong with their
data, and we plan to publish the schema publicly so that authors can
check their data against it when developing and testing.

Also, please note that we're not redoing the database or other major
backend components as part of the new API. This means that this is not
a good time or place to discuss new general features for Hoptoad.
However, this is the perfect place to discuss or request something
that would be useful to you as a notifier author.

I'm looking forward to everybody's ideas. Thank you all for you
participation.

-Joe Ferris
thoughtbot, inc.

[Steve Losh]

One thing I'd love to see is the ability to mark a notification as a
"test notification". It would be parsed normally by Hoptoad and the
normal response would be returned, but it wouldn't show up in the UI
at all. That would make it easy to write unit tests for plugins
without spamming a user's UI (and possibly inbox) with test
notifications.

--
Steve Losh
http://stevelosh.com/

[Corey Donohoe]

On Thu, Aug 6, 2009 at 4:57 PM, Steve Losh<stil...@gmail.com> wrote:
>
> One thing I'd love to see is the ability to mark a notification as a
> "test notification".  It would be parsed normally by Hoptoad and the
> normal response would be returned, but it wouldn't show up in the UI
> at all.  That would make it easy to write unit tests for plugins
> without spamming a user's UI (and possibly inbox) with test
> notifications.

I actually created a separate project to test integrations w/ the live
site.. We can spot check the UI to make sure stuff is working end to
end.

--
Corey Donohoe
http://atmos.org
http://engineyard.com
http://thetownhall.org

[Kevin Menard]

Aside from an XSD, it would be nice if each element were clearly
documented in wiki form. I know we spent a fair bit of time using
Hoptoad outside of a Rails app and trying to figure out what fields we
needed to set in order to get the Web display we were used to with our
Rails apps. I.e., it seemed that the Hoptoad display was very much
centered around a Rails request and exception. Not having an "action"
or a "controller," it would be nice to know which fields need to be
set and how it affects display and reporting.

--
Kevin

[Chris Wanstrath]

On Jul 29, 10:11 am, Joe Ferris <joe.r.fer...@gmail.com> wrote:

> Our current preference for a format is XML, because:
> * It has more parsers and generators (especially in other languages
> than Ruby)
> * It's easy to validate
> * Its validation documents can be distributed
>
> We have an example of what we think an XML request should like for the
> new API:http://gist.github.com/158180
>
> None of this is currently implemented or set in stone, so if you have
> ideas to improve this document, or if you have a compelling reason to
> use a different format, please let us know.

Does this mean we'll no longer be able to use JSON to submit errors?

We use Hoptoad outside of Rails and XML-only would be unfortunate.

Chris

[Joe Ferris]

Hi,

Steve: we'll certainly consider allowing notifications in "test" mode.
Thanks for the suggestion.

Kevin: we'll be rolling out improved documentation when we launch the
new API. We'll try to make sure it's clear what each element is, even
outside of a Rails or Ruby application.

Chris: our current plan is to only allow XML, yes. Supporting several
formats in the old API became a serious burden, both in terms of
application code maintenance and in terms of application performance.
We chose XML because it was easy to validate, it had distributable
schema documents, it had fast, streaming parsers, and it had good
support in many languages. If you plan on using the notifier outside
of Rails, but in Ruby, the new notification plugin should still work
fine for you. One of our major goals is to make it easy to format
exceptions outside of Rails. If you have specific needs regarding JSON
or other languages, please let us know. If you don't want to discuss
this publicly, please open a support ticket at http://help.hoptoadapp.com/,
and we can work together to ensure that Hoptoad continues to serve
you.

Thanks for your suggestions and your feedback.

-Joe

[Tim Lucas]

> Chris: our current plan is to only allow XML, yes. Supporting several
> formats in the old API became a serious burden, both in terms of
> application code maintenance and in terms of application performance.

Really? Like really really? I don't want to belittle software I know
little about, but it seems like a very small API footprint that needs
to be validated.

-- tim

[Joe Ferris]

Hi Tim,

We originally supported 4 formats: xml, yaml, json, and url-encoded
params. In each of these formats, there were situations in which the
Rails params parser would raise exceptions, or we'd get slightly
different data than we expected. In order to ensure that all four
formats continue to work, we'd need to maintain integration tests for
every situation in each format. We'd also need to update all the
tests, documentation, and code for four formats each time we updated
the API in any way. Considering none of the formats had any major
merits over any of the others, we've decided that this flexibility was
not worth maintaining. It may seem like validation is a small part of
the picture, but every piece of extra code is code we have to
maintain.

-Joe

[Tim Lucas]

On 17/09/2009, at 3:09 AM, Joe Ferris <joe.r....@gmail.com> wrote:

> We originally supported 4 formats: xml, yaml, json, and url-encoded
> params. In each of these formats, there were situations in which the
> Rails params parser would raise exceptions, or we'd get slightly
> different data than we expected. In order to ensure that all four
> formats continue to work, we'd need to maintain integration tests for
> every situation in each format. We'd also need to update all the
> tests, documentation, and code for four formats each time we updated
> the API in any way.

I agree on dropping multiple-format.

Is XSD going to save your chops though? An XSD doesn't count for
friendly API documentation, so you're either going to have to generate
and maintain separate docs or write code to generate the docs based on
the XSD.

> Considering none of the formats had any major
> merits over any of the others, we've decided that this flexibility was
> not worth maintaining.

The advantage JSON has over XML is that JSON can be represented as
arrays, hashs and strings, so it's extremely easy to generate, handle
and wrap in a library.

With it's element attributes, XML will always need HAML or Builder or
*insert other library here* in languages without language-level XML
support, to both generate and represent the data.

> It may seem like validation is a small part of
> the picture, but every piece of extra code is code we have to
> maintain.

I hear ya!

-- tim