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.