Tags API and Mashup Blog - Posts tagged with "api"

API Tip of the Day: Self documenting code is an ideal

Read the API carefully as you write it.  Does it read clearly?  Can new users make sense of it quickly?  Twitter’s “statuses/mentions” is a good example – you’ll HTTP GET the mentions of the user account you’re calling from.  Readable APIs mean easy-to-adopt APIs.

API Tip of the Day: Involve the users early

Your API exists for the use of developers.  You’ll probably get it wrong the first time.  With a tight feedback loop between developers who use the API and those who build the API you can get it right quickly.  In turn these early users will help promote the API and help new users get productive.

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)

Why modern applications need an API proxy

Structures of control are spontaneously generated in every environment and every wave of computing.

Today on the web we have a model where browsers are the single point of control for much of what happens, not just at the level of applications, but at the meta-application level as well. Not simply usage (“point-click-type”), but things about usage – who is the user (browser cookie), what are they using the app through (user agent), where did they come from (referrer), what can we infer about their behavioral state, and so on – as well as modifications of usage (browser add-ins, content filters, security modes, local caching for performance). To be sure, some of these things can be and are performed using infrastructure between the browser and the website (such as content filtering, security, and caching), but the guaranteed component is the browser.

This is one of the reasons that Google Analytics is so popular and useful – you can rely on it to tell you useful things about your traffic because it can rely on the browser as a predictable point of control. Including an invisible piece of content on your web page makes the browser fetch data from Google, implicitly sending information that enables Google to report on your usage.

For web and cloud APIs, what is the equivalent structure of control?

Currently there is no one point like the browser. This is for great reasons – APIs are all about reusing application or service logic and rendering it to different form factors: pure logic (built into an internal application computation), web UIs (part of a mashup), and most notably, client applications on a wide range of devices (from PCs to mobile phones, set-top boxes, and tablets like the iPad). These devices are in the early part of a boom that will see over 10 billion individual units in use, representing at least hundreds of unique hardware/software designs. The sheer utility of these internet-connected devices predicts that their usage will drive high demand for APIs rather than standard websites. There are initial specifications like BONDI that suggest a standard contract across all of these for “mobile web applications” that include interaction with the features of the local device (such as a camera or GPS) but they are years from broad adoption and don’t attempt to unify all API access down to a common control point.

Given that APIs are to application logic what RSS is for content, we know they will be very important; at least as important as the visible web that we use today and possibly more important. This suggests that the other things that are spontaneously generated in value-exchange environments like user/customer management, behavior analysis, content filtering, caching, and security – will show up for APIs as well.

The web API equivalent of the browser’s control structure is an API proxy.

This is a control point which unlike a web proxy is fully aware of API content, communications patterns, and able to drive the meta-application controls discussed above. An architecture like Google Analytics which is founded on a browser’s predictable algorithms cannot work in an API setting. The same rule applies to add-ons that modify usage – they can’t do so relying on the local device if they are to be widely adopted. But an API proxy – a server or service on the internet, sitting between the client (regardless of type) – is able to be that point of control. As traffic runs through it, meaningful data can be captured for immediate outcomes (block access, change the message, or respond from a cache) and later used for behavior analysis and business planning. Add-ons that modify usage of the API can be installed at this point (content filtering, adding new information such as advertising, or identity management). All of this can be done while adhering to the contracts of the APIs and supporting the web architecture and rules of HTTP-based applications, and without attempting to solve the logarithmically complex problem of modifications to all the world’s clients.

So API proxies are likely to be necessary for the sustained growth of web and cloud API usage. There are likely to be several nuances that end up differentiating the different implementations and providers of API proxies. The key is to start experimenting with them now in order to build better apps and stay ahead of the competition.

Flickr Photosets: Monitoring the Flickr API

Because Apigee is a tool used by people who build things on top of APIs, we get to see a lot of cool mashups and tools — Flickr Photosets is one of them, built using the Flickr and Facebook APIs proxied through Apigee.

It's easy to see why this app has so many fans. It's the fastest and most intuitive Flickr app we've seen on Facebook. You can also view and share your comments.  And it's an impressive example of how community can make an app better — with both open source code available for any facebook developer and a rich community discussion forum for users to suggest improvements.

Brad Dougherty, the app developer, uses Apigee to monitor usage, errors, and response time from the Flickr API. We appreciate Brad's great feedback such as making it easy to identify (and rate limit) different URLs by API method calls specified by parameters - we've heard that across a few users, and we are working on it. We asked Brad for his comments on working with Apigee and for what he's learned through this project.

Although my app hasn't had any downtime since I started using Apigee, it's a great way to monitor that calls to the Flickr API are actually working, something I haven't been able to see in the past. The biggest lesson I've learned from this app is that it can be very taxing to keep up with the changes in Facebook's API. It's a battle to keep adding new features when you keep having to change things to keep up-to-date with Facebook.

New features:  SSL support and “Remember-me”

Recently we rolled out two new Apigee capabilities.

First, we've added SSL support for APIs that support the HTTPS protocol. Now you can create an Apigee proxy for an API secured by HTTPS—such as the PayPal API—just specify 'https' in the API URL when creating a proxy. You could also change an existing HTTP proxy to an HTTPS proxy. (Of course, the API in question must support HTTPS, else you'll get an error.)

We're also working on adding SSL support for API providers that want to map to their own domain URL (and therefore their own certificate). Stay tuned, and you can review and comment on our proposed SSL Solution at anytime on our community area.   (You will see that we've completed sections 1 and 4 of the proposal to date..)

Secondly, we've added 'remember me' functionality on log-in.  We'll remember your login for 2 weeks so you don't have to specify your password, just head to app.apigee.com to see your proxies. This also means you can bookmark a favorite chart.

Thanks for the continued feedback—we're prioritizing features based directly on your input!