Netflix API Developer Blog

New API Proposal: Bulk Queue Update

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.

13 Comments

  1. Doron – 3 years ago

    Would I be able to somehow bulk up gets? Say I have search results and I want to check their format availability - I'd rather have one call rather than doing 1 per search result item.

  2. Hans Granqvist – 3 years ago

    Quick note: Bulk search operations are easier to map since each search can be executed independently. Input could be a list of searches and returns a list of result. Maybe a different type of input fits this operation better?

  3. eddiewebb – 2 years ago

    is the Queue State bulk update available yet? this would be extremely helpful!

  4. Hans Granqvist – 2 years ago

    Eddie,

    We have the code ready, but there are some holes in the OAuth spec how to secure non name/value data in requests.
    Any other content, such as XML, is left outside the signature, and therefore susceptible to man-in-the-middle attacks.

    There is a draft standard that addresses such signatures but it isn't standard yet.
    http://oauth.googlecode.com/svn/spec/ext/body_hash/1.0/oauth-bodyhash.html

    Here is some more background discussion on OAuth list:
    http://groups.google.com/group/oauth/browse_thread/thread/42ef5fecc54a7e9a

    We're figuring out the best way forward over the next few days. Please share your views!

    Hans

  5. eddiewebb – 2 years ago

    DOes not Google use OAuth for their APIs? I know they allow bulk operations using atom, would be interesting to see how they protect against MiM attacks. Maybe I am wrong though.

  6. Hans Granqvist – 2 years ago

    Good thinking. Yep, they do, but they bundle it all up in non-REST batched XML via POST. Interesting.

    See more:
    http://code.google.com/apis/gdata/batch.html

  7. eddiewebb – 2 years ago

    Just following up on this proposal from a few months back..

    My application, QueueMan, runs on Android phones, so connectivity and performance is a major issue. Having to make signed HTTP POSTS for each action as simple as shuffling Q order, and having to parse xml response is costly.

    A bulk update would have a huge impact on usability and perceived 'snappiness'

    Please escalate this task and keep us informed.

  8. Kurt – 2 years ago

    The first proposal doesn't suffer from the problem mentioned in comment 4, since all of the info goes into the query string, correct? I like that proposal better, too, because it allows you to update the entire queue. The second proposal can only update one "spot" of the queue for adds unless allowing multiple "insert_after"s, which gets tricky due to the ordering.

    Are both proposals going to be supported, or just the second?

  9. Hans Granqvist – 2 years ago

    Hi Kurt.

    We chose something slightly different. The bulk queue update takes as input a representation of the queue (just like you would retrieve it via the API) and makes the queue so. That is, you PUT a representation of the queue you desire to the API, and this representation -- barring errors in the input -- replaces the current queue, instant or disc.

    We will post further documentation in a short while.

    -Hans

  10. Tim Biron – 2 years ago

    Is there a pending release date for this new API?

  11. Michael Hart – 2 years ago

    We don't have a date to announce at this time.

  12. Chiriboga – 11 months ago

    EACH MOVIE AND TV SHOW SHOULD HAVE CLOSE CAPTIONS FOR THE HEARING INPAIRED IN ENGLISH AND OTHER LENGUAGES ALSO, SO THAT THE HEARING IMPAIRED CUSTOMERS CAN UNDERSTAND WHAT IS GOING ON IN A MOVIE OR TV SHOW;OTHERWISE FOR THEM IT IS NOTHING, BUT MERE MEANINGLESS IMAGES.

  13. touton – 4 months ago

    Very interesting. I have the domain names, internettvconcerts.com internettvcartoons.com internettvsitcoms.com internettvporn.net

    please contact me if you are interested. russchafe@hotmail.com

Please sign in to post a comment.