Everything Should Have An API
words.scottjackson.org
words.scottjackson.org
Text files have a super low-level API (stat, seek, read). I think the system he describes would be much more usable if he picked slightly higher-level data abstractions. I would recommend Python's built-in types: list, tuple, dict, set. Most data can be easily represented by these types and they provide a higher level API than streams (files), which means the barriers to using them are much lower.
I still really like text files though :)
Great post by the way, very thought provoking.
SQLite is one good example of a portable, open, simple format that is complementary to flat files. JSON and Lua also seem very Unix-y to me. Unix typically also uses ELF, various compiled key-value databases, etc.
Unix's choice of data types was also influenced by being written for computer that had 32k of RAM. That's, what, as much as a bar of soap nowadays?
1) An API can require even more planning to design than the application or service itself.
2) Mistakes made in the design or implementation of the API turn into liabilities you can't solve without breaking users of the API.
3) The cost of maintaining an API so that it and its documentation doesn't fall out of date with the app/service can be as high (and sometimes even higher) as the cost of maintaining the app itself.
4) It widens the attack surface.
And those are just the ones off the top of my head.
Another thing worth mentioning is the possibility of building your API first, and then building your service on top of it. If you are providing a web service, then it [usually] boils down to data access and management. Figure out what data you are managing for your users and what you need to do with it, then build your API around that. If you plan to have a public facing API from the start, this approach makes sense (in the same way that using javascript only for progressive enhancement of a working site makes sense).
Of course, because you are an "internal user" of the API, you can bend the rules a little more than the average client, but the less you do this, the more useful your API is.
Regarding points 2 and 4: if public APIs for data access become the norm, this will simply become the cost of doing business. Secure API's aren't that difficult, and updating an API while maintaining backwards compatibility can be done, especially if you transition these changes and notify all broken clients.
So many web apps are already built on top of an API or framework provided by a RAD tool. So if you build another API atop that then you'd lose the ability to enjoy the benefits of the RAD tool for the actual application--since it's now two levels away from it.
The point of an API is to have a clear interface so that programs can be built on a service, and captchas exist to try to block bots from using services.
do:
server->return any errors
client->display errors
client->ask user for account name
client->server->request account name x
while ( server->x is invalid account name )
<< Repeat above loop for password >>
do:
server->return new captcha
client->display captcha
client->take user input
client->server->send captcha text
while(server->captcha does not match)
server->return success messageTake one of his example scenarios:
"When my alarm clock goes off in the morning, get the latest tech news podcast (downloaded overnight) from my computer via WiFi or a wired network connection. Play the podcast through the alarm clock’s speaker/s. If I hit “snooze” on the alarm clock, pause the podcast. Once I stop the alarm, remember where I was up to in the podcast and give that information back to my computer. Now when I go to listen to the podcast while I’m eating breakfast, it will continue playing where it left off."
This has a number of hidden assumptions:
* What is "the latest news podcast"? One user-selected source, or a blended filtered combination, or a crawled set selected based on previous behavior?
* How does a (not the!) computer know how to talk to the alarm clock? I hope I don't have to create a home network myself, cause I know my Mom certainly can't. How is this connection authorized? What happens if the power goes out on the computer - what will the clock do? What if the clock batteries fail - will the computer play the podcast instead?
* Is the saved position synced only the one source computer (I hope not). What if the network to the computer is down - can the alarm clock sync somewhere else?
* Can I resume listening to the podcast on a different computer at breakfast? My partner/sibling/friend's computer? How do I log in? How is the position data saved along with my identity? How does the breakfast computer address the first computer, or the alarm clock?
The problem here is not access to the external APIs (not that hard) but federation, identity management, authorization, privacy considerations, and addressing between these disparate systems. Proposal adopting existing standards for these requirements, or new proposals for standards are, of course, appreciated.
Like I said in another thread, I am just a peon with access to a keyboard. I trust that there are developers and system-setter-upper-ers much smarter than I who could put this into place.
I don't know how much of the example scenario you could implement within the confines of UPnP, but perhaps it could be part of the solution.
On the other hand, tools to do this with almost any site already exist. RSS is common enough, and where it doesn't exist, screen scraping isn't that hard (and getting easier all the time). If I'm not mistaken, this is the exact problem that Yahoo pipes are trying to address.
Of course, sites that require a complicated login process (banking sites) are still out.
As more companies become Google-esque data hogs, APIs will probably be encouraged.
Also consider that the bank would get blamed in popular opinion if someone wrote an insecure client that was determined to be leaking data.
If we don't make APIs because someone might write an insecure client, would anyone make any APIs ever?
I do agree with you though :) It's probably not going to happen in the real world any time soon. C'est la vie.
But consider for example if Bank of America did this and someone created an awesome client app that basically became the main way anyone used their Bank of America account. If a bug is discovered in this application that means everyone's data is no longer secure, are users going to blame the app creator or Bank of America? Can Bank of America afford to take that chance?
Though, didn't Bank of America make that iPhone app a little while ago that allowed you to photograph a cheque in order to deposit it? They're obviously OK with sending financial data around. I guess maybe it was OK in that case because they were the ones that wrote the app?
In any case, you're right. Security is definitely the reason this kind of stuff hasn't been implemented. I still think that it's possible to write an open, secure interface to things. Email is the example I fall back on here. Like I mentioned above - sensitive information gets sent around in emails all the time, yet there are countless email clients and they're almost all secure (I say "almost all" to cover my ass if there's some that aren't). I think that if it can work for email, then maybe it can work in other domains.
That said, there was an excellent article recently with the experiences of a trainer in getting people to use *nix, who found the minimalistic "command mode" more usable due to it's text oriented simplicity.
Everything should talk to one another, but a service's name or url should never have to appear in any code. That's the user's job to input.