Pownce is currently in an Alpha State (very alpha) so publishing API information really doesn’t make sense when theres still potential to make large changes to the application. But what if you want to use it anyway? You have what i see to be 3 options.
1. Wait for Pownce to release information about a public API. (Smart Move)
2. Wait for someone else to figure out the API and publish information about it. (Saves time) Someone has just released a python api on googlecode.
3. Figure it out for yourself. Seemingly is a major pain figuring out an API you really can’t (shouldn’t) use in any application you would make public. However, if you have the time it can be fun. Like a puzzle.
Anyway, I chose option 3 and these are the basic steps i took in getting the API up in going in a Flex app.
1. The first hurdle. Got Invite?
Sign up for Pownce and install the AIR application. (if you need an invite let me know)
2. You talk’n to me? The Packet Trace.
In order to use the API we need to understand how the the AIR application is communicating with the server. In order to do this we’re going to watch the network traffic on our computer. There are several programs out there that can help with this, but I just use tcpdump on osX.
2.1 Open up the Terminal in osX
2.2 Run the following command:
sudo tcpdump -i en2 -vvv -n -s 0 -w ~/Desktop/PownceTrace.dmp
(for more information http://developer.apple.com/qa/qa2001/qa1176.html)
2.3 Launch Pownce.
2.4 Login to Pownce.
2.5 Close your Terminal
2.6 Open the PownceTrace.dmp file in a text editor and you will see something like the following:
GET /api/login/ HTTP/1.1
Accept: */*
Accept-Language: en
Accept-Encoding: gzip, deflate
Cookie: sessionid=96b063edc2713808a0b11440ec432691
Referer: app-resource:/PownceDesktop.swf
User-Agent: Pownce Alpha Desktop 0.5
Authorization: Basic aW5pdGssDfdafdafafafadfdfa==
X-Flash-Version: 9,0,28,0
Connection: keep-alive
Host: pownce.com
POST /api/notes/for/initapp/?auth=UsernameToken%20Username%3D%22initapp%22%2C%20PasswordDigest
%3D%fdafafsfdasfafdasfafdsafadfafda22%2C%20Nonce%3D%22MDQ1NzkzMjcxNzE2Njg0MTAz%22%2C%20
Created%3D%222007%2D07%2D05T14%3A16%3A44Z%22 HTTP/1.1
Accept: */*
Accept-Language: en
Accept-Encoding: gzip, deflate
Cookie: sessionid=96b063edc2713808a0b11440ec432691
Referer: app-resource:/PownceDesktop.swf
User-Agent: Pownce Alpha Desktop 0.5
Content-Type: application/x-www-form-urlencoded
X-Flash-Version: 9,0,28,0
Content-Length: 202
Connection: keep-alive
Host: pownce.com
3. The Hill of Beans
So now what? Lets figure out the authentication.
Figuring out the authentication is the simple part. Seeing “Authorization: Basic aW5pdGssDfdafdafafafadfdfa==” is the tip off that we’re dealing with a simple Basic Authentication scheme (http://en.wikipedia.org/wiki/Basic_authentication_scheme). The twitter api also uses this. Basic authentication is Base64Encode(name:password).
ActionScript:
var urlRequestHeader:URLRequestHeader = new URLRequestHeader(“Authorization”, “Basic ” + base64Encode(userName + “:” + userPassword));
Next i took the GET /api/login/ HTTP/1.1 dropped http://www.pownce.com/api/login/ into firefox.
Response:
<login token=”4Ol+EZZZ8×518RRfdadfafdaoGW0IPu0E=”>
<user pro=”0″ maxuploadsizemb=”10″>
<atom:author>
<atom:name>Steven G.</atom:name>
<atom:uri>http://pownce.com/InitApp/</atom:uri>
<username>InitApp</username>
<image>http://pownce.com/profile_photos/I/n/i/InitApp/9440_medium.jpg</image>
</atom:author>
</user>
</login>
4. It can’t be this easy can it? Nope…
In order to send/receive messages we need to figure out the following:
/api/notes/for/initapp/?auth=UsernameToken%20Username%3D%22initapp%22%2C%20PasswordDigest
%3D%fdafafsfdasfafdasfafdsafadfafda22%2C%20Nonce%3D%22MDQ1NzkzMjcxNzE2Njg0MTAz%22%2C%20
Created%3D%222007%2D07%2D05T14%3A16%3A44Z%22 HTTP/1.1
With the login response and the “auth=UsernameToken” I was able to determine that we’re using what looks like the Atom API and WSSE. In order to get the PasswordDigest we’ll need to understand this. I read Atom Authentication at “http://www.xml.com/pub/a/2003/12/17/dive.html” and figured out that
PasswordDigest = Base64 \ (SHA1 (Nonce + CreationTimestamp + Password)).
To get the WSSE authentication in actionscript 3 we can turn to the as3corelib (http://as3corelib.googlecode.com/svn/trunk/docs/com/adobe/crypto/package-detail.html)
userAuth = com.adobe.crypto.WSSEUsernameToken.getUsernameToken(userName, password);
5. Step Five: Admit that you have no idea what you’re doing.
So now we have it all figured out. We can authenticate the user and generate the userAuth for each request. At this point, I’m beaming with excitement. But disappointment sets in quickly when after generating the request i would only receive invalid credentials. When I took the same Nonce and Date and used it to with my username token from username and password, I could never get a match. So I pulled out my hair for awhile and then just let it sit.
6. Research. The internet holds the secrets.
In searching the internet about information regarding WSSE I happen to run in to a blog post written by “Michal Migurski” who worked on the digg api:
Michal “This post is a run-down of various patterns we’ve encountered for authenticating applications and users, and has been greatly helped along by conversations with Shawn, Steve, Matt, and others.”
The Shawn he is refering to is “Shawn Allen” who has written the pownce API. Ok, now we’re getting somewhere.
The key parts of the post to me comes in these 2 sections:
Michal “WSSE has come under a great deal of criticism due to its requirement that the password be part of the hash. No sane application developer stores passwords in cleartext, but WSSE requires that this be the case in order for the server to re-create the hashed token for comparison.”
In the next paragraph
Michal “Amazon’s web services define their own authentication protocol… Second, instead of asking for an account password, Amazon assigns each API user a secret key for use in such hashes.”
Read it all:
http://foocamp.crowdvine.com/feeds/show/1226?type=blog&scope=profile
6. Oh thats the stuff!
1. They would never send the password with each request. (I’m assuming they’re sane)
2. Amazon uses “secret key” instead of the “password” in hashes.
The secret key reminded me of the <login token=”4Ol+EZZZ8×518RRfdadfafdaoGW0IPu0E=”> received after the login.
At this point I replaced :
com.adobe.crypto.WSSEUsernameToken.getUsernameToken(userName, password);
with
com.adobe.crypto.WSSEUsernameToken.getUsernameToken(userName, token);
The API is now open. There was some additional weirdness in the url encoding which I have working in the downloadable example. I plan on looking at the python version to see what they’ve done. I glanced at there googlecode site and it looks like a lot of good information is building up. http://code.google.com/p/python-pownce/
I guess the point of this post isn’t so much to hand out how to use pownce in your app as it was how much fun you can have in solving the puzzle.
You could say its a technical mystery and you’re the detective.
Code Disclaimer:
The code is rough. I started to create an API for pownce based on how the Digg api was done. Parsing the atom feed for the notes quickly made me realize that in order to be done correctly, it would be… you know, work. So I stopped and the code contained allows you to post a public note and retrieve your private notes. Do not use this code for any public applications.
Download Example Code
On the other side of it, its been a long time since I’ve been this excited about a new technology (like a kid again) and for that I’m thankful. Without the flex team/flex community keeping me filled with cool new things almost daily, I think the anticipation of Apollo would have driven me crazy a long time ago.
