Ideas on making the Lighthouse API better: making ticket creation not suck

I like to think that we have a pretty decent Lighthouse API. It doesn’t handle attachments yet (have you tried to upload multipart file content with ruby? yuck!), and a few other things, but it’s good enough to enable the creation of something like Lighthouse Keeper.

Jeremy and I were just discussing some ideas for a new Lighthouse client library (more on that later once it’s not so vaporous. Then Kyle chimes in:

Zing!

There are definitely some pain points we need to address there. I’ve mostly been focusing on issues like poor/outdated documentation and major omissions (attachments). But in the meantime, I’ll probably throw out some helper API calls to make some of this common stuff better.

If you happen to follow edge Rails work, I recently posted about autoloading api schemas in ActiveResource. This works by requesting the #new action and using those values as the defaults for your newly instantiated objects. This is fine and dandy, and has been supported and included in the Rails resource scaffold for awhile. But, how do you deal with properties that are filled by drop downs? It’d be nice to be able to return the available values in the returned data from the #new action:

{"ticket":
  {"title": "", "assigned_user_id": null}
 "attributes":
  {"assigned_user_id": [
    {"id":1, "name": "bob"}, {"id":2, "name": "fred"}]}}

That example doesn’t really translate well to XML. I strongly prefer JSON, but there’s no way I can remove XML support. So, here are a couple other ideas we had:

<ticket>
  <assigned_user_id nil="true" />
  <valid_options>
    <assigned_user_id>
      <assigned_user>
        <id>1</id>
        <name>bob</name>
      </assigned_user>
    </assigned_user_id>
  </valid_options>
</ticket>

This puts the available values under a single property. Though it makes the nested xml harder to deal with. Here’s another approach.

<ticket>
  <assigned_user_id nil="true" />
  <assigned_user_id_options>
    <assigned_user>
      <id>1</id>
      <name>bob</name>
    </assigned_user>
  </assigned_user_options>
</ticket>

These conventions allow client libraries like ActiveResource to properly filter out the values that aren’t actual property values into some list. Either way would allow you to build your own new object form from a single call. Does anyone else have any thoughts on making this possible? Are there existing APIs that I could look at? Should I keep it simple and rely on the client to sufficiently load and cache these options?