The Interaction Design
of APIs
Stanford HCI Group
Seminar on People, Computers, and Design
April 17, 2009
Alex Payne
API Lead, Twitter, Inc.

Select Language ...
What is Twitter? Watch a video!
What? Why? How?
Please sign in
user name or email address:
password:
Sign In »
Remember me
Forgot password? Click here.
Already using Twitter from
Twitter is a service for friends, family, and co–workers your phone? Click here.
to communicate and stay connected through the
exchange of quick, frequent answers to one simple
question: What are you doing?
Get Started—Join!
Suddenly, it seems as though When I first started doing it, I Incredibly useful
all the world's a-twitter. thought, 'geez, not another
website to worry about
Wired
updating and checking', but

FrontPage
Create a page
EDIT
VIEW
Pages & Files
Upload files
Settings
FrontPage Help
last edited by Doug Williams 1 day ago Page history Search Pages and Files
Welcome to the Twitter API wiki. What are you coding?
Send a link
Put this page in a different folder
Documentation
Frequently asked questions Add Tags
REST API Documentation Page Security
Search API Documentation
REST API Changelog
Migrating to followers terminology
Navigator
Official resources
Official Resources
REST API issue tracker - file bugs, request features FrontPage
Request whitelisting
Libraries
@twitterapi - follow to get updates about the API
Twitter API Announcements Google Group Migrating to followers terminology
Moderators
OAuth
REST API Changelog
OAuth FAQ
OAuth Examples REST API Documentation
Pages No Files
Community Resources
SideBar
Twitter Development Talk Google Group

Alex Payne writes online here.
See also the archive, books & talks.
The five most recent posts.
Mending The Bitter Absence advertisement
of Reasoned Technical
Discussion
There’s a counterpart to my post on technology journalism Delicious bookmarks on
that I’ve been hesitant to write. Just as most professional your iPhone. Now
journalism on high technology fails us today, so too does available in the App
Store!
the online discussion amongst technologists as a
POWERED by FUSION
community.
Social media (blogs, community news sites like Reddit and Hacker News,
Twitter and such) have swept in to fill a vacuum between peer-reviewed
academic journals and water cooler conversation amongst software
engineers. Anyone with a blog can publish development war stories,
benchmarks, or an interview with another developer. It’s a world of
engineer’s notebooks laid wide open, and in theory, we should be more
informed as a profession than we ever have been.
In practice, the conversations that are most widely heard in the tech
community are full of inaccuracies, manufactured drama, ignorance, and
unbridled opinion. In discussing these Internet-spanning debates with non-
technical friends, comparisons to Hollywood tabloids come first to mind.
It’s a time sink for an industry that should be a shining example of how to

What’s an API?

Why do we care
about making good APIs?

Why does this matter
to an HCI person?

The Twitter API
2 years old
•
40 methods
•
4,500+ registered developers
•
5,000+ registered applications
•
multiple books (English, Japanese)
•
an even larger “invisible” ecosystem
•
hundreds of millions of requests per day
•

What do people build
with the Twitter API?

How does it feel?

http://twitter.com/statuses/show/1516683992.json
{
\"text\":\"Kitty, don't boss me. I will feed you in due time.\",
\"truncated\":false,
\"in_reply_to_status_id\":null,
\"in_reply_to_user_id\":null,
\"favorited\":false,
\"in_reply_to_screen_name\":null,
\"id\":1516683992,
\"source\":\"web\",
\"created_at\":\"Tue Apr 14 13:47:41 +0000 2009\",
\"user\":
{
\"statuses_count\":6426,
\"description\":\"No ideas but in things.\",
\"profile_background_tile\":false,
\"utc_oset\":-28800,
\"profile_text_color\":\"41446c\",
\"following\":true,
\"profile_link_color\":\"ad102d\",
\"url\":\"http:\\/\\/blog.evanweaver.com\",
\"name\":\"Evan\",
\"notifications\":false,
\"profile_sidebar_fill_color\":\"\",
\"followers_count\":2308,
\"protected\":false,
\"profile_background_image_url\":\"http:\\/\\/s3.amazonaws.com\\/twitter_production\\/profile_background_images
\\/6920721\\/BD2_1024-1.jpg\",
\"friends_count\":117,
\"profile_sidebar_border_color\":\"d5d4ec\",
\"time_zone\":\"Pacific Time (US & Canada)\",
\"profile_image_url\":\"http:\\/\\/s3.amazonaws.com\\/twitter_production\\/profile_images\\/111994468\\/
BD2_1024_2-1_normal.jpg\",
\"favourites_count\":1032,
\"location\":\"Russian Hill, California\",
\"id\":761613,
\"created_at\":\"Fri Feb 09 22:59:00 +0000 2007\",
\"profile_background_color\":\"7b9ab7\",
\"screen_name\":\"evan\"
}
}

What makes it easy?
low barrier to entry: “just poke at it”
•
human-readable names
•
logical nesting of resources
•
predictable output
•
constrained set of object models
•

What frustrates developers?
inconsistency
•
anything vague or unpredictable
•
lack of user interface conventions
•
network and performance issues
•

A shameful glimpse at bad APIs.

import java.util.{Calendar, Date}
lazy val updatedDate = {
val rfc3339 = new SimpleDateFormat(\"yyyy-MM-dd'T'h:m:ss'-05:00'\")
val calendar = Calendar.getInstance
calendar.set(year.toInt, month.toInt - 1, day.toInt)
rfc3339.format(calendar.getTime)
}
java.util.Calendar, java.util.Date

//Call SecKeychainAddGenericPassword to add a new password to the keychain:
OSStatus StorePasswordKeychain (void* password,UInt32 passwordLength)
{
OSStatus status;
status = SecKeychainAddGenericPassword (
NULL, // default keychain
10, // length of service name
\"SurfWriter\", // service name
10, // length of account name
\"MyUserAcct\", // account name
passwordLength, // length of password
password, // pointer to password data
NULL // the item reference
);
return (status);
}
//Call SecKeychainFindGenericPassword to get a password from the keychain:
OSStatus GetPasswordKeychain (void *passwordData,UInt32 *passwordLength,
SecKeychainItemRef *itemRef)
{
OSStatus status1 ;
status1 = SecKeychainFindGenericPassword (
NULL, // default keychain
10, // length of service name
\"SurfWriter\", // service name
10, // length of account name
\"MyUserAcct\", // account name
passwordLength, // length of password
passwordData, // pointer to password data
itemRef // the item reference
);
return (status1);
}
//Call SecKeychainItemModifyAttributesAndData to change the password for
// an item already in the keychain:
OSStatus ChangePasswordKeychain (SecKeychainItemRef itemRef)
{
OSStatus status;
void * password = \"myNewP4sSw0rD\";
UInt32 passwordLength = strlen(password);
status = SecKeychainItemModifyAttributesAndData (
itemRef, // the item reference
Keychain Services, Mac OS X
NULL, // no change to attributes
passwordLength, // length of password
password // pointer to password data

BOOL CALLBACK AboutDlgProc(HWND hwnd, UINT Message,
case WM_COMMAND:
WPARAM wParam, LPARAM lParam)
switch(LOWORD(wParam))
{
{
switch(Message)
case ID_HELP_ABOUT:
{
case WM_INITDIALOG: {
int ret = DialogBox(GetModuleHandle(NULL),
return TRUE; MAKEINTRESOURCE(IDD_ABOUT), hwnd, AboutDlgProc);
case WM_COMMAND: if(ret == IDOK){
switch(LOWORD(wParam)) MessageBox(hwnd, \"Dialog exited with IDOK.\", \"Notice\",
{ MB_OK | MB_ICONINFORMATION);
case IDOK:
}
EndDialog(hwnd, IDOK);
else if(ret == IDCANCEL){
break;
MessageBox(hwnd, \"Dialog exited with IDCANCEL.\", \"Notice\",
case IDCANCEL:
MB_OK | MB_ICONINFORMATION);
EndDialog(hwnd, IDCANCEL);
}
break;
else if(ret == -1){
}
MessageBox(hwnd, \"Dialog failed!\", \"Error\",
break;
MB_OK | MB_ICONINFORMATION);
default:
}
return FALSE;
}
}
return TRUE; break;
} // Other menu commands...
}
break;
Win32

http://api.yelp.com/neighborhood_search?location=1512%20Shattuck%20Avenue%2A%20Berkeley%2A%20CA&ywsid=XXXXXXXXXXXXXXXXXX
{'message': {'code': 0, 'text': 'OK', 'version': '1.1.0'},
'neighborhoods':
[{'city': 'Berkeley',
'name': 'Gourmet Ghetto',
'borough': '',
'state': 'CA',
'state_code': 'CA',
'country': 'USA',
'country_code': 'US',
'url': 'http://yelp.com/search?/find_loc=Gourmet+Ghetto%2C+Berkeley%2C+CA' },
{'city': 'Berkeley',
'name': 'North Berkeley',
'borough': '',
'state': 'CA',
'state_code': 'CA',
'country': 'USA',
'country_code': 'US',
'url': ' http://yelp.com/search?/find_loc=North+Berkeley%2C+Berkeley%2C+CA'}]
}
Yelp

A brief tour of excellent APIs.

class CreateSavedSearches < ActiveRecord::Migration
def self.up
create_table :saved_searches do |t|
t.column :user_id, :integer
t.column :name, :string
t.column :query, :string
t.column :position, :integer
t.timestamps
end
add_index :saved_searches, :user_id
end
def self.down
drop_table :saved_searches
end
end
Rails Migrations

$('form#login')
.find('label.optional').hide().end()
.find('input:password').css('border', '1px solid red').end()
.submit(function() {
return confirm('Are you sure you want to submit?');
});
jQuery

import scala.actors.Actor._
val echoActor = actor {
loop {
receive {
case msg => println(\"received: \" + msg)
}
}
}
echoActor ! \"hello\"
echoActor ! \"world!\"
Scala Actors

What are the qualities
of good APIs?

Explorability.

REST vs WS-*
A case study in explorable APIs.

Smalltalk Environment

SLIME
(the Superior Lisp Interaction Mode for Emacs)

Predictability.

ODBC, JDBC, etc.
A case study in predictable APIs.

Consistency.

The options Hash in Rails
A case study in consistent APIs.

file_field(:post, :attached, :accept => 'text/html')
file_field(:attachment, :file, :class => 'file_input')
text_area(:post, :body, :cols => 20, :rows => 40)
text_area(:comment, :text, :size => \"20x30\")
text_area(:entry, :body, :size => \"20x20\", :disabled => 'disabled')
submit_to_remote 'create_btn', 'Create', :url => { :action => 'create' }
Rails Helpers

The Humane API:
explorable
predictable
consistent

Thank you for listening.
Questions?