Netflix API Developer Blog

This is our first blog posting soliciting feedback on a future Netflix API.  The post is also the first by Hans Granqvist, one of our API team developers.      -Mike

A queue bulk operation makes it easier to perform queue managment. Currently one must make do with multiple API calls to adds, deletes, format changes, and moves. The set of calls can be tricky to get right, and each call also counts against your quota.

We're adding bulk operations to the API. Here are the two main types of APIs we're considering. Let us know which one you think works best and why!

QUEUE STATE

The bulk operation input is a representation of what the queue should look like.  It ignores current queue state and replaces the queue.  If a title contains multiple discs those discs will be added beginning at the index specfiied.  The indices of other titles with are adjusted to make room for the additional titles.

Since this is a modification in place, is idempotent, and ignores previous state of the queue it uses the PUT method.

PUT /users/userID/queues/{disc|instant}

Parameters

title_ref[n]


req.   The catalog title to be in position [n] of the queue.




format[n]


opt.   The format of the title in position [n]. Default format for queue used if not specified.




Etag


opt.   ETag value returned last time queue was read.




OAuth 



req.   Consumer key + access token + signature

Result      

200
Success



400 (660)

If given format is not available for the user in the queue



304

If incoming queue representation is equal to current.



412

Etag concurrency error



500

Internal error. Partial replace of queue may have occurred.

Possible variations include:

• Use XML/JSON to pass the queue params.
• Impose an order to the title references, so accepting a sequence of {title_ref,format} would be enough to represent the queue without the added positional marker.
• In addition, we could accept a subset of the queue with the same semantics as above, so that the subset given replaces corresponding subset in the queue, and queue items skipped will remain unchanged.  This would mean that bulk deletes wouldn't be possible, since omitted queue items would be skipped vs. deleted.

SEQUENTIAL OPERATIONS
 
For this version, input is a list in terms of inserts, deletions, and modifications, intended to be executed in sequence.

Since this is a modification that is not idempotent (issuing the same request twice may change the queue twice) it uses the POST method.

The resource is the same as other proposal. There is a clash here with the existing POST operation on the queue, so care has to be taken to pass input params correctly.

  POST /users/userID/queues/{disc|instant}

Input format
The input format to this proposal uses XML/JSON.

Parameters

inject_after  Keyword takes a position + list of titles
deleted       Keyword takes a list of titles

Template:

{
  'inject_after' : [n, title foo, ..., title bar],
  'delete' : [title baz}]
}

Example:

{
  "delete" :   
  [
   "http://www.netflix.com/Movie/The_Tale_of_Despereaux/70075482", 
   "http://www.netflix.com/Movie/Lakeview_Terrace/70098896" 
  ], 
  "inject_after" : [1, 
   "http://www.netflix.com/Movie/Mac_and_Me/70000001"
  ]
}

Results

We anticipate being able to use the set of results codes that is used by existing API operations around queue updates.

To discuss: should multiple 'inject_after' and 'delete' arrays be supported? If so, then a second 'inject_after' with a positional argument will have dependencies on previous inserts (since they shift elements in the queue) -- which is very tricky to get right, especially when adding a TV seasons that results in multiple DVD adds.

I tend to go by "JR" a good deal. There's lots of reasons for that, but suffice to say that amongst my friends, family and co-workers, if you asked about "JR" they would know who you were talking about. Widening that circle out a bit more, however, things start getting a tad fuzzy. Folks might wonder if you meant a character from an 80's nighttime soap, or the Japanese Railroad, or an Electronics Retailer who folks continually forget also contains an ampersand. Turns out, while it's mighty handy short-hand, using the two major letters of my hyphenated first name isn't terribly good at uniquely identifying me.

For that, you'd need to toss in a lot of extra information that may be redundant with my neighbor, or the guy who stood behind me at the Social Security desk years ago. It's also the reason that there's a sizable chunk of information one needs to provide for absoulte identification, because, unfortunately, we're analog creatures who just don't map that well to digital references.

The same can be said for a lot of the titles in our catalog. If I say "Batman", what am I referring to? Do I mean the latest movie featuring that character which doesn't have his name in the title? The 1989 movie? The Animated series (by either Paul Dini or the newer one)? The Classic 1966 TV series? Or do I mean the 1940's Serial? Truth is, "Batman" just isn't good enough. What's more, these things tend to change around a good deal. A one off TV special may strike an unexpected chord with an audience, return as a Series, that eventually winds up being a movie.

When it came time for us to try and figure out what to use as an identifier for a given title in our catalog, there was a lot of arguing. Eventually, what won out was the most REST-ful approach we had, which was to make a movie's ID are resolvable URL. The nice thing about this approach was that you, dear programmer, didn't have to suss out and build some complicated URL in order to get things, but instead could walk our catalog pretty easily. Unfortunately, the problem is that we may have done too good a job at making it easy.

Folks wanted to find patterns. They thought that since 90% of the ID looked the same between 10 randomly picked movies, they could toss out the "extra" bits. Unfortuantely, it really doesn't work like that. It's a bit like saying "Well, everyone with the first name "Bob" in zip code 60609 has the last name of "Smith" so I don't need to store that." That approach works great right up until Bob Johnson moves in.

I'll even note that while the ID currently resolves to a nice URL, it may not always do so. The ID will still work as a movie ID however.

All this is a long winded way of saying Treat the ID as an opaque value, don't try taking it apart and "find the value". It may work for a bit, but you're just going to drive yourself nuts when it doesn't later. The movie ID is the full on value in the ID field. So when I refer to movie "http://api.netflix.com/catalog/titles/movies/70039237" we'll both know exactly what I'm talking about.

If you have 2 1/2 hrs and feel like watching something different, here are some fairly new Instant Watch titles to check out at your leisure. I found these at instantwatcher.com, while playing around with our App Gallery

• Jodhaa Akbar  - (Historical w rich costumes)
• A Peck on the cheek

This is an example of how great apps and tools could do the magic for you. Go ahead and poke around and see what else folks have built.

Having trouble getting one of the steps in the OAuth Dance exactly right? The Netflix Authentication Walk-Through is here to help. Through the magic of copy-and-paste, the Walk-Through will guide you from your first token request all the way through to adding, changing, and deleting live user queue items. There's nothing to install on your end; everything works from your browser, with nothing to install or manage.

The Walk-Through is also useful for testing. You'll be able to use your own application's callback, if you like. You'll be able to view your signed URLs all the way through the process, which is especially handy if you're having trouble understanding (or rolling your own) OAuth library.

One of the developers made a reasonable observation that the app gallery should accept portrait-oriented screenshots given the number of mobile Netflix apps out there.  This is now supported.  The same dimension restrictions are enforced, but the image can now be either in landscape or portrait orientation.

As the OAuth community and other news outlets are reporting, a security exposure has been identified with the OAuth protocol’s application authorization process we use to allow third-party applications to access the Netflix service on a subscriber’s behalf. 

The Netflix website and our partner movie players (listed here) do not utilize OAuth and are therefore unaffected by this vulnerability.  Netflix javascript widgets on sites like The New York Times and Rotten Tomatoes are also unaffected.

After examining the threat in the context of the API capabilities we provide, we’ve determined that the risk is not substantial enough to suspend our OAuth support at this time.

We have taken steps to minimize the risk to our subscribers by minimizing the validity period of OAuth request tokens which makes the attack more difficult to orchestrate.  We have also added a warning to our OAuth application authorization page to warn subscribers about the potential risk and help them identify if they are taking part in a compromised authentication session.  In the coming days, we’ll continue to work with Mashery and the OAuth community to resolve the exposure.

More information on this issue is available at the OAuth website.  We will notify the developer community via this blog if our policy on this issue changes as well as any modifications to our OAuth support.

The soon-to-be-released Netflix App Gallery is now open for developer submissions!  You can create your entry for the gallery by going to the "My Account" page on the developer portal and then selecting the "My App Gallery Entry" link.

A couple items to note:

1. We'll launch the Gallery to Netflix members when we feel we have a minimum list of applications.  We don't expect this to take that long given the number of apps out there.
2. While the Entry details page says that the application description is limited to "100 chars or less", we'll support longer descriptions of up to 600 characters on the application detail page and show the first 200 characters of that description when your application will be shown in list views.  Note that you can supply a link from your app entry to a more complete application description, download link, etc.
3. Reminder: each submission will be reviewed for Terms of Use compliance before it is published to the Gallery.

We're looking forward to promoting your applications to Netflix subscribers!  Please comment on this post using the link below if you have any questions or comments around submissions.

We're very happy to announce that we're about to roll out an App Gallery to showcase all of the great applications you developers have built using the API.  The App Gallery will be on the main Netflix website, so this is going to be a terrific way to tell our subscribers about your application.

The Gallery will be rolled out in two phases.  In the first phase, we'll accept application submissions.  Once we have a decent initial set of applications will open up the Gallery on the Netflix website.

We're giving developers advanced notice of the launch so that you have extra time to address any Terms of Service compliance issues before we start accepting submissions.  We will be doing quick audits of all submitted applications, and the last thing we'll want to do is reject an application due to compliance issues. 

The most common compliance issues we've see to-date have to do with branding violations or improper OAuth implementation, whereby the application requests user name and passwords directly vs. handing the user off to our OAuth sign in page.  When in doubt, ask us for guidance in the forums.  Chances are, someone else has a similar question.

We'll do another blog posting as soon as the Gallery is open for submissions as well as send a tweet from the netflixapi Twitter account.

First off, huge thanks to David Westbrook, John Haren, Kirsten Jones, and Johnathon Wright. Why? Because these really smart people build libraries to call into the Netflix API. Thing is, they're not alone. There are other folks that have also built great libraries that do amazing things and generally keep you from having to read and implement that confusing section in our docs about how to handle request tokens.

Only we don't know who they are.

We'd love to, because I'd happily list them on the resources page and point folks at the well forged sweat of their respective brows in the forum, mail lists, twitter, and everywhere else I find folks looking for an easy answer. The only problem is, we can't do that unless you tell us about them.

(As a wise man once told me, "If you build something and nobody knows about it, why did you waste your time?")

So, please, let us be your cheerleaders. Tell us about your libraries so we can send you folks who need them, and thus ensure your fame, glory and accolades for generations to come. If your library isn't listed in the Showcase, (or you know of one that's not) please feel free to include it.