Wednesday, October 29, 2008

Parsing API Results - XML vs. JSON

There is an option to get JSON format or XML format back from the API. I'm investigating ways to parse JSON to see if its easier than XML (simply add output=json to the URL call).

My open source google code efforts are on hold for now since I have much more demand for new features in my app than people asking for source code. Let me know if you want code and I will assist on a case by case basis. Later on I will post cleaned up code to the google code project.

Friday, October 10, 2008

Netflix API - Parsing the results of an API call - Part 5

One of the first API calls I needed to call gets the user's name and other information. In my case all I need is the first and last names, and the flag that says whether the user can use instant watching. This flag is set true for main accounts, and false for account profiles that don't have an instant queue.

The return data from the API call is in XML format, so this code shows how to use the XML parser to pick information out of the data returned from an API call. I provide a convenience method that combines the first and last names, and I didn't need the other link information, so it is ignored, but the code could easily be extended to pick it out as needed.

Some of the code below doesn't display properly. I'm going to set it up in google code soon to make it easier to manage.


//
// NetflixUser.h
// Instant Flix
//
// Created by Adrian Cockcroft on 10/8/08.
// Copyright 2008 millicomputing.com
// Licenced using Creative Commons Attribution Share-Alike
// http://creativecommons.org/licenses/by-sa/3.0/

#import


@interface NetflixUser : NSObject {
NSData *rawData;
NSString *first_name;
NSString *last_name;
bool can_instant_watch;
NSXMLParser *userParser;
NSString *currentElement;
}

@property(readonly) bool can_instant_watch;

- (NetflixUser *)initWithAPIResponse:(NSData *)response;
- (NSString *)name;

@end






//
// NetflixUser.m
// Instant Flix
//
// Created by Adrian Cockcroft on 10/8/08.
// Copyright 2008 millicomputing.com
// Licenced using Creative Commons Attribution Share-Alike
// http://creativecommons.org/licenses/by-sa/3.0/

#import "NetflixUser.h"

/* Sample returned raw data

[userid]
Adrian
Cockcroft
true













*/

@implementation NetflixUser

@synthesize can_instant_watch;

- (NetflixUser *)initWithAPIResponse:(NSData *)response {
rawData = response;
[rawData retain];
first_name = nil;
last_name = nil;
can_instant_watch = NO;

//NSString *responseBody = [[NSString alloc] initWithData:response encoding:NSUTF8StringEncoding];
//NSLog(@"NetflixUser: %@", responseBody);

userParser = [[NSXMLParser alloc] initWithData:rawData];

// Set self as the delegate of the parser so that it will receive the parser delegate methods callbacks.
[userParser setDelegate:self];
[userParser setShouldProcessNamespaces:NO];
[userParser setShouldReportNamespacePrefixes:NO];
[userParser setShouldResolveExternalEntities:NO];
[userParser parse];

return self;
}

- (NSString *)name {
return [first_name stringByAppendingFormat:@" %@", last_name];
}

- (void)parserDidStartDocument:(NSXMLParser *)parser{
//NSLog(@"started parsing");
}

- (void)parser:(NSXMLParser *)parser parseErrorOccurred:(NSError *)parseError {
NSString * errorString = [NSString stringWithFormat:@"Unable to parse XML (Error code %i)", [parseError code]];
NSLog(@"error: %@", errorString);
}

- (void)parser:(NSXMLParser *)parser didStartElement:(NSString *)elementName namespaceURI:(NSString *)namespaceURI qualifiedName:(NSString *)qName attributes:(NSDictionary *)attributeDict{
//NSLog(@"found this element: %@", elementName);
currentElement = [elementName copy];
}

- (void)parser:(NSXMLParser *)parser didEndElement:(NSString *)elementName namespaceURI:(NSString *)namespaceURI qualifiedName:(NSString *)qName{
//NSLog(@"ended element: %@", elementName);
currentElement = nil;
}

- (void)parser:(NSXMLParser *)parser foundCharacters:(NSString *)string{
//NSLog(@"found characters: %@", string);
// save the characters for the current item...
if ([currentElement isEqualToString:@"first_name"]) {
first_name = [string copy];
} else if ([currentElement isEqualToString:@"last_name"]) {
last_name = [string copy];
} else if ([currentElement isEqualToString:@"can_instant_watch"]) {
if ([string isEqualToString:@"true"]) {
can_instant_watch = YES;
} else {
can_instant_watch = NO;
}
}
}

- (void)parserDidEndDocument:(NSXMLParser *)parser {
//NSLog(@"found %@ who %@ instant watch", self.name, (can_instant_watch? @"can": @"cannot"));
}

@end

Wednesday, October 1, 2008

Netflix API - Netflix Specific OAuth iPhone Code - Part 4

I have already discussed how to get OAuth to build for an iPhone in Part 2. To use OAuth to call Netflix there are two small changes needed. The first one is that the way that characters are escaped in URLs needs to be tightened up a bit, otherwise the signature strings will work some of the time and fail when they happen to contain the wrong character sequence. This took a while to figure out...

The file NSString+URLEncoding.m needs to have a few characters (space, plus and asterisk) added as shown below:

Note, I'm having a hard time getting code to look good here, its hard to find a way to render code in a narrow column that doesn't mess up the formatting and works in more than one browser using blogger.com tools and templates.

- (NSString *)encodedURLString {
NSString *result = (NSString *)CFURLCreateStringByAddingPercentEscapes(kCFAllocatorDefault,
(CFStringRef)self,
NULL,
CFSTR("?=& +*"), // legal URL characters to be escaped
kCFStringEncodingUTF8); // encoding
return result;
}

- (NSString *)encodedURLParameterString {
NSString *result = (NSString *)CFURLCreateStringByAddingPercentEscapes(kCFAllocatorDefault,
(CFStringRef)self,
NULL,
CFSTR(":/= +*"),
kCFStringEncodingUTF8);
return result;
}


The second thing is that when the authentication is complete, Netflix returns a token that contains an encoded user identifier, as well as a secret and a key. The standard OAuth code only expects the secret and key, so a new NetflixToken class was created to hold the extra information, and to persist it in the iPhone's defaults store along with the secret and key. This means that once the user has signed into OAuth once, this information is saved and they never have to sign in again unless either Netflix or the User revokes the token. One more method was added to remove an entry from the defaults store, for use during logout.

First the NetflixToken.h header file:

//
// NetflixToken.h
// Instant Test
//
// Created by Adrian Cockcroft on 9/11/08.
//

#import
#import "OAToken.h"

@interface NetflixToken : NSObject {
@protected
NSString *key;
NSString *secret;
NSString *user;
}
@property(copy, readwrite) NSString *key;
@property(copy, readwrite) NSString *secret;
@property(copy, readwrite) NSString *user;

- (id)initWithKey:(NSString *)aKey secret:(NSString *)aSecret user:(NSString *)aUser;
- (id)initWithUserDefaultsUsingServiceProviderName:(NSString *)provider prefix:(NSString *)prefix;
- (id)initWithHTTPResponseBody:(NSString *)body;
- (int)storeInUserDefaultsWithServiceProviderName:(NSString *)provider prefix:(NSString *)prefix;
- (int)removeFromUserDefaultsWithServiceProviderName:(NSString *)provider prefix:(NSString *)prefix;
- (OAToken *)oaToken;

@end


Then the code itself, this is all based on a simple extension of OAToken, which is part of the OAuth code base mentioned in part 2.


//
// NetflixToken.m
// Instant Test
//
// Created by Adrian Cockcroft on 9/11/08.
//

#import "NetflixToken.h"

@implementation NetflixToken

@synthesize key, secret, user;

#pragma mark init

- (id)init {
[super init];
self.key = @"";
self.secret = @"";
self.user = @"";
return self;
}

- (id)initWithKey:(NSString *)aKey secret:(NSString *)aSecret user:(NSString *)aUser {
[super init];
self.key = aKey;
self.secret = aSecret;
self.user = aUser;
return self;
}

- (OAToken *)oaToken {
return [[OAToken alloc] initWithKey:self.key secret:self.secret];
}

- (id)initWithHTTPResponseBody:(NSString *)body {
[super init];
NSArray *pairs = [body componentsSeparatedByString:@"&"];

for (NSString *pair in pairs) {
NSArray *elements = [pair componentsSeparatedByString:@"="];
if ([[elements objectAtIndex:0] isEqualToString:@"oauth_token"]) {
self.key = [elements objectAtIndex:1];
} else if ([[elements objectAtIndex:0] isEqualToString:@"oauth_token_secret"]) {
self.secret = [elements objectAtIndex:1];
} else if ([[elements objectAtIndex:0] isEqualToString:@"user_id"]) {
self.user = [elements objectAtIndex:1];
}
}

return self;
}


- (id)initWithUserDefaultsUsingServiceProviderName:(NSString *)provider prefix:(NSString *)prefix
{
[super init];
NSString *theKey = [[NSUserDefaults standardUserDefaults] stringForKey:[NSString stringWithFormat:@"OAUTH_%@_%@_KEY", prefix, provider]];
NSString *theSecret = [[NSUserDefaults standardUserDefaults] stringForKey:[NSString stringWithFormat:@"OAUTH_%@_%@_SECRET", prefix, provider]];
NSString *theUser = [[NSUserDefaults standardUserDefaults] stringForKey:[NSString stringWithFormat:@"NETFLIX_%@_%@_USER", prefix, provider]];
if (theKey == NULL || theSecret == NULL)
return(nil);
self.key = theKey;
self.secret = theSecret;
self.user = theUser;
return(self);
}


- (int)storeInUserDefaultsWithServiceProviderName:(NSString *)provider prefix:(NSString *)prefix
{
[[NSUserDefaults standardUserDefaults] setObject:self.key forKey:[NSString stringWithFormat:@"OAUTH_%@_%@_KEY", prefix, provider]];
[[NSUserDefaults standardUserDefaults] setObject:self.secret forKey:[NSString stringWithFormat:@"OAUTH_%@_%@_SECRET", prefix, provider]];
[[NSUserDefaults standardUserDefaults] setObject:self.user forKey:[NSString stringWithFormat:@"NETFLIX_%@_%@_USER", prefix, provider]];
[[NSUserDefaults standardUserDefaults] synchronize];
return(0);
}

- (int)removeFromUserDefaultsWithServiceProviderName:(NSString *)provider prefix:(NSString *)prefix
{
[[NSUserDefaults standardUserDefaults] removeObjectForKey:[NSString stringWithFormat:@"OAUTH_%@_%@_KEY", prefix, provider]];
[[NSUserDefaults standardUserDefaults] removeObjectForKey:[NSString stringWithFormat:@"OAUTH_%@_%@_SECRET", prefix, provider]];
[[NSUserDefaults standardUserDefaults] removeObjectForKey:[NSString stringWithFormat:@"NETFLIX_%@_%@_USER", prefix, provider]];
[[NSUserDefaults standardUserDefaults] synchronize];
return(0);
}
@end

Netflix API - Announcement - Part 3

Here is the official announcement of the API and how to get access to it.

Starting Wednesday, Oct. 1 the Netflix API is open to all:

The Netflix API:

- Allows access to data for 100,000 movie and TV episode titles on DVD as well as Netflix account access on a user’s behalf
Netflix has more than 2 billion ratings in its database
Netflix members rate more than 2 million movies a day
Netflix ships more than 2 million DVDs on a typical day

- Is free

- Allows commercial use
E.g. if a developer creates an iPhone app and wants to sell it for $0.99, that’s ok

Technically, the Netflix API:

- Includes a REST API, a Javascript API, and ATOM feeds

- Uses OAuth standard security to allow the subscriber to control which applications can access the service on his or her behalf

Developers can get access:

- Starting 10/1

- By self sign up at http://developer.netflix.com