I like writing API wrappers, and I've actually written quite a few over the past year -- including ones for the EPA's API, the St. Louis FRED API, and the Rotten Tomatoes API. I also created a site (with an external API) to help add some panache to your boring Lorem Ipsum text.
Writing API wrappers is as much as about heuristics as anything else. So, instead of writing long paragraphs of opinion masquerading as insight, I'll keep the following section somewhat short and sweet -- with plenty of code examples, as well.
Maximum four words per line. That's the goal. This heuristic does kind of tie-in with the magic number seven, plus or minus two concept. Basically, the less you have to remember, the better.
>>> Wrapper().does('something', 'yay!')
Methods should be one word long.
>>> Bus().stop('1234')
{"stop": {"1234": "data"}}
The wrapper should look out for the developer. It should be easy-to-use, and, instead of throwing errors for common mistakes, it should just go ahead and correct the mistake.
>>> Bus().stop(1234)
{"stop": {"1234": "data"}}
Empty method calls should return something if possible -- a great example would be a list of possible values.
>>> Bus().stop()
[1234, 5678, 9999]
If it makes sense, pluralized methods should work as well. Again, ease-of-use for an API wrapper is key.
>>> Bus().stops()
[1234, 5678, 9999]
A developer should be able to pass keyword arguments into a method.
>>> Wrapper().does('something', greeting='hello')
{"ohai": {"greeting": "data"}}
A developer should be able to dictate the returned content type if possible. Some weirdos like XML, so go ahead and let them work with it.
>>> Wrapper('xml').does('something')
"<ohai><xml><data></data></xml></ohai>"
>>> Wrapper().does('something', format='xml')
"<ohai><xml><data></data></xml></ohai>"
Don't reinvent the wheel. Build on top of already existing libraries -- especially if they're awesome and well-tested.
With that in mind, your code should be well-tested. Not 80% or 90% test
coverage -- but an entire 100%. It's a solid practice that pays off and
kind of ensures you won't go crazy with if/else logic (since you have
to write a test for each of those conditions).
So why should you write an API wrapper?
It's easy and contributes to the better good. You might not make a million dollar app off of the API and API wrapper, but some developer somewhere will probably find a solid use-case for it.
It's easy and makes you a better developer. I'm serious. Writing an API wrapper has a good bit of psychology and design to it -- it's all about predicting the easiest way for an individual to use a service (that may or may not be a complete pain otherwise).
It's easy and can be put on your resume. It never hurts to author a few helpful libraries and release them to the world on Github, right?
It's easy. Seriously, an hour or two of your time can really pay off and help less technical users and developers trying to access data. I know a few graduate students around the country have used my FRED API wrapper to work around having to mess with XML.
I'm going to be biased and say that if your project isn't on Github, it basically doesn't exist. You may or may not disagree with that statement, but most developers would probably tell you the same -- especially if you're open-sourcing the code (which you should be).
Now that's out of the way, there's a great list of APIs on Programmable Web that you can take a look at. You can also send a tweet for ideas to either Code for America or myself, as well.