Friday, June 24, 2011

Code for America, Week 3: Why API auto-generator DNE

Well, aside from dreaming of rideable hexapods, during the day time I am working away on code for america developer tools project. Namely, I have been learning about how to write a python API wrapper, and attempting to learn how to write a good one.

Stackoverflow was not so helpful in this regard:

Re: the autogeneration question that is working on, RJ explicates:
I think you'll be hard pressed to automate this. Few if any APIs come with a machine readable description of what they are and how they work. This is because it's really hard. It'd be a great thought exercise to try and come up with a schema or ontology for APIs, but even if you did almost no APIs would use it so it wouldn't matter anyway.

Incidentally, the core of REST is this very thing -- self-descriptions of how to consume an API that eliminate the need for the API's wrapper in any given language from needing to know any hardcoded information about resources provided by the API. (e.g. the wrapper doesn't have to know that the Person resource is provided by the URL route /people/

Almost no so-called "REST API" is truly a REST API, because it does not provide this self-description. What people latched on to by calling things "REST" is that its simple, state-less, idempotent, and based on the 4 actions get / create / delete / put. Everyone conveniently leaves off that last requirement of REST because it adds more complexity and the way everyone implements API wrappers is by saying "let me read the API human documentation and poop out some Python that can do everything it's capable of".

another reason why auto-generating an API wrapper would be hard -- people, especially programmers, are highly aesthetic. Every target language has their own community standards and principles for how things are supposed to work (e.g. "Pythonic") so your wrapper generator will have to somehow account for this to not offend the programmer's sensibilities. My gut feeling is that most machine-generated wrappers will be stuck in some kind of uncanny valley where it'll feel crappy.

I think Google Protocol Buffers are a good example of this. While they are awesome, no way would you think that the code auto-generated for interacting with a protobuf was written by a human, because all the method names are very machine-like (i.e. pluralizations aren't quite English -- think "num_citys").

Well, you're right that this kind of thin-wrapper [edit:
around an API is not very expressive. As a Python API writer, I think I would far prefer something similar to how the Django ORM expresses database queries. Something like this would be nice:

class Business(RESTResource):
type = ... (enum type)
zipcode = ... (string)

businesses = Business.get().by_zipcode(zipcode).filter(type=business_type)

(nevermind that zipcode is not l10n-considerate)

Meanwhile, Zach, my fellow Python devtools intern, has been working on an awesome generic Python API wrapper template which is well-documented to boot:

Also helpful was studying the Sunlight Labs python code:
And looking at this, although perhaps it's not the best example:

These are all for the simple APIs, of course.

I've certainly learned a lot, but I'm also 100% the code I'm writing right is crap. That's okay though, I decided to forge ahead, learn things, and come back and fix it later. Otherwise, I'll never get anything done.

Oh also look we're on the internet!

And also fellowship applications are open~
2012 Fellowship Application
Application Deadline: 8/1/2011 | Program Start: 1/4/2012
Online application:
Learn more:
Nominate a fellow: | @codeforamerica

The office is in downtown San Francisco, and the area is ... awesome. You peer out the office window and Instructables is across the street, delicious food is plentiful, close-by, and varied, there's random talks and people coming by, and you'll get emails like "github drinking night" or some such. The office has an awesome atmosphere of teamwork and getting things done.

That's my "I'm homesick for a place I spent a week in" spiel :) I haven't had face-to-face contact with people in forever, and today there was a hardware talk going on that I just pestered people until someone gave in and let me skype in. Then I realized how much I miss the office, haha.

Friday, June 10, 2011

Code For America, Week 1: 10 Internets of Awesome

It's the start of my google summer of code 2011 internship at Code for America, a week Dan Melton, our CTO, has termed the "bootcamp." Whew. It's been a crazy week for me. I didn't know what they expected, since I fall into a lot of categories:

  • Female
  • From MIT
  • Not a full-blown CS major
  • Haven't had a real programming job before
  • Have never contributed to open-source code
The first few days or so I lived in constant fear that they would find out they hadn't gotten what they'd bargained for (I seriously considered resigning). I'm closer to believing that they'll accept me the way I am, clueless and all. For a while I wondered: was I only here (despite my lack of expertise in python/github/FOSS development) because I was a female or because I was from MIT? Then the feminist side of me came out and was like "screw that I shouldn't have to think those thoughts, I was admitted for better or for worse so let's just get on with it."

Anyway, for me it's been a whirlwind tour of once again, getting over my aversion to asking for help. WTF, it's pretty obvious I'm completely inexperienced, why am I still afraid to show the extent of my uh lack of anything in my brain?

Hehe. Ah well, it's Friday, which is open labs (work on whatever you want), and I'm in a happy mood and fine with the fact that I still need to improve myself.

Learned/learning this week:
Github, git
Serious python development: nose, mock,
Vi plugins: minibufexplorer, janus, solarizer, nerdtreeexplorer
Dotfiles .bashrc .vimrc .coveragerc
How to be humble and also how to not run away and hide in my dreams
APIs and devtools and how to write wrappers, RPC, JSON, XML, REST, http headers, chrome inspector navigator
App deployment (in 5 minutes o.o) and some of the services out there
Continuous integration server for python
Fabric, python eggs

Talks this week:
Coda Hale, metrics
DJ Patil, LinkedIn / color
Twitter product head, cofounder random questions

Wednesday, June 1, 2011

2d tshirt printer + soluble ink for one-time shirts

most t-shirts are for one-off events anyway, and while they're good for memories, really? do we need that many t-shirts? kind of wasteful.

of course the craftier among us can reuse the cloth to create awesome individualized clothing...

but another solution might be the t-shirt printer (DIY Direct-to-garment:

combined with a soluble ink of some kind. Most t-shirt inks are designed with permanence in mind (to prevent fading with repeated washing). And the erasability of the ink has to be balanced against not wanting the ink to come out during a hot summer day (heat + sweat or rain). Ideally it would come off in ordinary washing machines, and it wouldn't stain other clothing when it washed off.