Observations on API and Mashup Management API and Mashup Blog

API Tip of the Day: Don’t put verbs in your API

The accepted verbs for REST APIs are contained in the HTTP Request: GET and POST.  Realistically PUT and DELETE are not always available due to IT standards for security on web servers.  Try to design your interface from the point of view of using just GET and POST as your verbs.

API Tip of the Day: Learn from the masters

Joe Gregorio’s original column from 2004 is just as relevant today as it was then. It covers the four fundamental design questions that authors of a REST API must ask and answer. Find it here: http://www.xml.com/pub/a/2004/12/01/restful-web.html

API Tip of the Day: REST Means Exposing a Resource

Ideally an API exposes a resource that can be manipulated.  While there may be multiple ways to organize those resources into categories and lists, at the end of the URL you are exposing a resource.  This is a core principle of the REST pattern.  Look at the problem from the resource’s perspective, not the perspective of the method.

Why your sweet new feature needs an API. Now.

Over the weekend, Twitter developer Alex Payne posted a tweet (since deleted) which sent such waves of speculation rippling through the Twitterverse that even Techcrunch felt the need to comment. Of course I'm interested in seeing the features that Alex wrote about, but I'm even more interested in Al3x's follow up tweet that noted, "We still release most everything API-first, of course."

Twitter, as much as anyone, has depended upon their API to drive adoption. This is the future of web services. The web IS the common ground, but as the web moves beyond browsers into devices like mobile phone apps, APIs are what allows it to happen. When you consider that 60% of all eBay listings are made via their API, then you have to appreciate how important APIs are.

If you want your developers to succeed, you have to empower them. Until you release most everything API-first, you aren't giving your developers the tools they need to push your platform forward. Take LinkedIn, for example. Their search API docs suggest that you cannot search LinkedIn by email address or phone number, even as an authenticated user. 

An email address is critical for disambiguating users. Imagine that I use a CRM system, like Highrise, and I want other users to be able to authenticate with LinkedIn to see who in the company might have a LinkedIn connection with a contact. What if that contact has a common name, and the only other information entered is an email address? The ability to identify specific people to see how you're connected is a primary use of the LinkedIn network. And yet third parties don't have access to these fundamental methods. Without this, their digital hands are tied. 

What's hot: releasing most everything API-first
What's not: leaving core functions out of any API

An API at Launch: Reflecting on the Google Buzz API

Remember when videogames used to be released on different platforms at different times? One platform like the PlayStation version would lead, while other versions trailed behind. Then at some point, publishers realized they could make a bigger splash by landing all versions in stores at once—the simultaneous release.

Today on the web we expect an API to lag the launch of a new webservice. So it was interesting to see Google Buzz tout its API on day 1. On one hand the shiny new Buzz API is not much more than a stub, though on the other it is a promise to deliver a robust API.

But at this time, you can't even post an update to Buzz via the API. You also can't mute a buzz. You can't even search. It's read-only; all you can do with the API is get the Atom feed for a user's Buzz, which doesn't include important metadata like location information. You could argue, as Fred Wilson has, that any read-only API shouldn't even qualify as an API.

There ARE things to like about the promise of the Buzz API. It's a stake-in-the-ground to support existing standards like PortableContacts, the Social Graph API, and OAuth. Important protocols like PubSubHubbub, Salmon, and WebFinger should get a good boost too. Yay for open standards!

But there are some concerns too. In order to build on top of the Buzz API, you may have to become familiar with the disparate set of technologies listed above. And if you prefer JSON or raw XML responses to Atom, you'll have to wait (FWIW, format conversion is one of the many tricks that Sonoa's ServiceNet does right out-of-the-box).

What could Google do to encourage Buzz innovation? After all, isn't that a big reason why APIs get released? They could wrap the various standards they plan to support with a look and feel similar to the full Buzz API (whenever it lands). They could emulate the Twitter API, like Wordpress and Tumblr have done, but that brings up issues of licensing—something that Googler Dewitt Clinton has pursued with Twitter's Ryan Sarver. Still, that kind of familiarity would only drive Buzz adoption with developers already versed in Twitter. In some ways Buzz resembles FriendFeed more than Twitter. So why not map the FriendFeed API pattern onto the Buzz API, as Dave Winer has suggested (again not without issues)?

Not having API in 2010 is like a not having a website in 1997. How long will it be until everyone launches both of them at the same time?

(logo by Alex Gillis)