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:
http://stackoverflow.com/questions/517237/howto-write-python-api-wrapper

Re: the autogeneration question that mashape.com 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!
http://codeforamerica.org/2011/06/15/meet-the-2011-cfa-interns/

And also fellowship applications are open~
2012 Fellowship Application
Application Deadline: 8/1/2011 | Program Start: 1/4/2012
Online application: http://codeforamerica.org/fellows/apply/
Learn more: codeforamerica.org/fellows
Nominate a fellow: c4a.me/fellow-nom
info@codeforamerica.org | @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.