INTRODUCTION

Web Application developers now have access to massive user presence and data from facilities such as "Yahoo Mail", "Microsoft's Windows Live" and "Google's Apps".

The business driver behind these APIs is to gain their share of eye balls and to put the best family of applications that can help keep life around us simplified and enjoyable.


Each one of these APIs come with excellent set of documentation and sample programs. However, it is rare for any set of documentation to possibly answer all the questions of the developers. So, we undertake a hands-on exposition of the APIs and this usually tends to bring out the developer connection to these APIs.

Problem Statement

a. Use Cases and System Overview

The goal here is to test drive the yahoo mail services API Version 1.0.0.0. Figure 1. above identifies typical use cases for an email service. We need to identify the use cases that we will test drive in this excercise.

One of the more interesting use cases is, "searching an emailbox". Unfortunately, yahoo mail APIs allows this only for those premieur accounts. Hence in this excercise, we shall settle for a lesser use case, namely, managing your mail folders, if you have a regular yahoo account.

**Notice that while Yahoo Mail APIs can be unleashed on a full service premieur user Account, you will have limited functionality with regular accounts.

b. Provide Feedback

We will take lessons learnt from our hands-on excercise and provide feedback to the companies through their developer network, where it may benefit even more developers.

YAHOO MAIL WEB SERVICE APIS

The Yahoo mail web services API is simply a web accessible Interface providing access to the yahoo mail facilities.

In geek speak, if you are familiar with namespaces and Interfaces, yahoo mail apis are part of a name space called YmwsSample. The later sections invoke a small subset of the API.

LIFE ACCESSING YAHOO MAIL FACILITIES

An application gaining access to the yahoo mail facilities goes through four stages. Figure 2.0 provides a birds eye view of the stages and this section explores them in more detail.

Step 1. Register your Application

As an application developer, yahoo requires you to register your application with Yahoo's Login facilities.

Yahoo End Point:

As a result of the registration, your application is provided with,

A.) An AppID

This appears to be a 40-character string. For .e.g, the following string closely resembles an AppId issued by the yahoo facilities, "V4HzGd7IkY6UOQEn0gF2za4pteR9sRPwxLCBHSA-"

B.) a secret pass phrase

This is a string that resembles to, "65ca4c0b73833687342b5d4a6d8f555d5"

Your application uses this information to later identify itself as a registered application to any of the yahoo facilities it tries to access, such as the yahoo mail or yahoo photos.

Step 2. User Authorization

Once, you are an yahoo registered application, you are one step closer to accessing the yahoo mail facilities.

a. "Establish a Data Session"

Your application needs to establish an user authorized data session with yahoo facilities prior to accessing the user data. Once your application establishes a session, it remains valid for a set time frame of about 14 days, as decided by yahoo. At the end of the session period, your application needs to re-establish a new session. Yahoo returns a token that represents the data session.

b. "Get User Credentials"

When the user authorizes access to their data, your application is provided with the equivalent of an username and password. This information needs to be passed along with every call to the Mail web service APIs. Yahoo calls them the WSSID and the auth cookie, respectively.

Step 3. Accessing the Mail Service API

The Yahoo mail web services Interface definition can be imported or referenced into your project. The interface and the namespace that it contains is named as "YWMSSample" and the "YmwsSample.com.yahooapis.mail" respectively.

In case, you are developing a C# application, Yahoo provides a pre-built DLL that has the type library defined and a sample program that calls each of these APIs.

MOTIVATION

The idea for this article came from reading a book named "Implementation Patterns". The author Kent Beck is a renowned programmer. One of Kent's observations is to design and write software with economics in mind, as software begins to play a bigger role in the corporate food chain. He points out, "Software should be designed to reduce cost".

For many organizations, software has become a key building block in their business Infrastructure. Recently, I came across a company who are in the direct mail business, the fliers that you get in your mail box advertising stuff. Now, they are exposing their entire infrastructure as an internet service for clients to order personalized US postal mail over the Internet.

In the new distributed world of computing, infrastructures that were traditionally not exposed to the outside world are suddenly finding themselves exposed to the naked call of far flung users through web service APIs.

REDUCING COST

As businesses are key drivers of the software, it interests them to understand and manage the cost.

If we care to represent the software cost into an equation,

Cost_Total = Cost_Develop + Cost_Maintain

Now, the second part of our cost equation can be rewritten as,

Cost_Maintain = Cost_Understand + Cost_Change + Cost_Test + Cost_Deploy

If your goal is to reduce and control the cost of software, which one of the above activities interests you the most and is likely to give the best bang for the buck?

For e.g., Would you spend more time upfront software design, hoping a better design saves you cost in the future, asks Kent? He points out, a dollar today is worth more than it is tomorrow. Hence, the suggests a deferrance of costs to a later time, where that is possible.

Offcourse, there is a saying, "Build to the requirements known at the end of the project and not the ones at beginning of a project." Agile methods anyone?

READABILITY

It is interesting to see there is a cost to understand someone else's code. Kent points out, it is not unusual for developers to think of computers as the ultimate consumers of their code and bother less about readability. Instead, he suggests a mindset that thinks that every line of code you write is for the consumption of a human being. Now, that changes our outlook. Doesn't it. That someone that reads that code in some distant tomorrow could be even you.

METAPHOR: CODING A STORY

Have you ever thought of your software as a story to be read by someone?

Kent goes on to suggest practical ideas to economize on the cost of your code. He and Ward Cunningham, the inventor of CRC cards, took a well written program and rewrote it, completely. They said, whenever, they felt a part of the program needed more comments or explanation, they simply rewrote it to make it more readable. They were pleased with their end result.

WHAT IS IN A NAME?

Kent suggests a metaphorical process and attention to details such as the naming of the classes in your software design. When you choose a name that immediately suggests to the reader the purpose of the class, you have done your job well.

As a simple example, here is a software service that handles emails and has an interface named as IMessages. The APIs in this interface are, Send, Get, Delete

The point here is, choose names whose meaning aptly represents the context in which your class operates and hence becomes obvious to the reader. Thus, you have reduced the cost of understanding your software and hence saved monies.

MORE EXAMPLES

Well. What about a more complex example, you ask.

Recently, I was tasked with prototyping an email client. I had to find a name for a class that establishes a TCP session with the server and does the donkey work of transporting emails back and forth. Initially, I named it as INetManager, 'cause I figured it manages the network. Then I renamed it as INetConnect 'cause it establishes a connection to the server. Finally, I renamed it as IMailTransport. The fact is this class sets up the transport that sends and receives mail back and forth from the server. The name represents just that. Now, I am off to naming my class that handles POP3 protocol and am still scratching my head to come up with an appropriate name.