Common Netflix REST API Tasks

Netflix API 1.5 Programmer’s Guide: Common REST API Tasks

This page provides some guidelines and examples to help you use Netflix API 1.5. It covers the following topics:

Using the API: a general description of how to use the Netflix API
Sample API Code: two simple examples: one example shows how to do a catalog title search and the other shows how to add a title to a user's instant-watch queue
Performing Basic Application Tasks: a list of common tasks with which API resource you use to accomplish each task

Using the API

This section describes in general terms the steps you need to take when you use the Netflix API.

Get the proper authorization. Do any necessary user login steps and OAuth authorization.
Set up parameters. Decide which parameters you are passing to API and set their values or retrieve those values as input from the user of your application.
Build the request to the API. The request consists of the full URL to the API resource itself, plus the parameters and their values.
Make the request. You invoke each request with its appropriate HTTP method: GET, PUT, DELETE, or POST.
Get the response and parse it for the data you need. Some of the data may be contained directly within the response, marked by appropriate tags, and some data may appear in the form of links to other resources.
Use the response data to do further operations. You can use the links within a response to make other resource requests. For example, if you retrieve details about a title, the response includes URLs for box-art images that accompany that title. You can use these URLs to access and display the box images. As another example, you might do a catalog title search, which returns resource references to the cast members and directors associated with each title. You could then use these references to retrieve details about these people.

Sample API Code

The sample code included here illustrates how you might use Netflix API. The samples show a simple search for a catalog title and the process of adding a title to a user's instant-watch queue.

Example: Search for Title

The example below uses the catalog/titles resource to search for instant-watch movies or television shows whose title matches some string. (While the example uses JavaServer Pages code, you can use any suitable language of your choice.)

<html> <head><title>Simple Search Page</title></head> <body> …
<% //callback Response resp = null; Strong sTerm = request.getParameter("term"); ← Get search term
if( sTerm != null ) {   String sRequest = ← Build request
   DemoApp.getService().buildRequestURI("/catalog/titles?term="+sTerm);   resp = DemoApp.getService().call(sRequest, Method.GET, null); ← Submit request to the server
} %> <table> <tr><form action="simplesearch.jsp"><td></td>   <input type="text" name="term" />   <input type="submit" /></form></tr> <% if( resp != null ) {   DomRepresentation rep = resp.getEntityAsDom();   Document doc = rep.getDocument(); ← Get the response
  XPath xpath = XPathFactory.newInstance().newXPath();   NodeList nodes = ← Evaluate the response
   (NodeList) xpath.evaluate( "/catalog_titles/catalog_title", doc, XPathConstants.NODESET );   for( int i=0, n=nodes.getLength(); i<n; i++ ) {    Node node = nodes.item(i);   Retrieve the data of interest:
   String sTitle = (String) xpath.evaluate( "title/@regular", node, XPathConstants.STRING );    String sImage = (String) xpath.evaluate( "box_art/@large", node, XPathConstants.STRING );    String sID = (String) xpath.evaluate( "id/text()", node, XPathConstants.STRING ); …
  } } %> <tr><table>tr align="center"> <img src="<%=sImage%>" /><br /> <%=sTitle%><br /> <form action="addToQueue.jsp">   <input type="hidden" name="title_ref" value="<%=sID%>" />   <input type="submit" value="ADD" /> </form><br /></tr></table> </tr> …
</table></body></html>

The above example prompts the user to enter a title, then builds a request to search the instant-watch catalog for matches on the term entered by the user. The request consists of the API resource's full URI, http://api.netflix.com/catalog/titles, with any parameters, such as the search term, added at the end of the URI. (The example uses its own method buildRequestURI( ) to construct the complete URI.) The code adds the parameter name and value to the end of the resource reference, first placing a question mark (?) followed by the actual parameter name (in this case, term), an equals sign (=), then the string holding the parameter value (sTerm). Once it constructs the request, it uses the HTTP GET operation to send the request to the server.

When the response is received, the code extracts the information of interest and displays it. The /catalog/titles resource returns a response with the representation catalog_titles . Each title entry in the returned document is in a catalog_title element, and each piece of data for an individual title is identified with a tag. Some of the title information is contained directly in the response, such as the average rating and release year date, while many of the other title details are URL links themselves, which you could use to pull in more information for display. This example evaluates the tags in the response and displays the title and the box art image.

Example: Add a Title to a User's Instant-Watch Queue

This next example shows how to add a selected title to a user's instant-watch queue. This example also uses JavaServer Pages code as its implementation language, but you are free to use another language.

<body> <% Response resp = null; NFOAuthAccessor user = null; try {   user = DemoApp.getUserData( request, response ); ← Set up user access
  if( user == null ) return; } catch( RedirectException e ) {   response.sendRedirect(e.getTargetURL());   return; } String sURL = ← Build request
  DemoApp.getService().buildRequestURI(    "/users/user_id/queues/instant?title_ref=" +    request.getParameter("title_ref")+"&method=POST", user ); resp = DemoApp.getService().call(← Submit request to server
   Method.GET, sURL, null, user ); %> <table><tr> <form action="search.jsp"><td></td> <input type="text" name="term" /> <input type="submit" /></form></tr> <% DomRepresentation resp = resp.getEntityAsDom(); ← Get the response
if( resp.getStatus().isSuccess() ) { ← Check if successful
  Document.doc = rep.getDocument();   XPath xpath = XPathFactory.newInstance().newXPath();   NodeList nodes = (NodeList) xpath.evaluate( "/result/associated_resources/queue_item", doc, XPathConstants.NODESET );   for( int i=0, n=nodes.getLength(); i<n; i++) {    Node node = nodes.item(i);    Display titles in queue:   String sTitle = (String) xpath.evaluate( "title/@regular", node, XPathConstants.STRING );    String sImage = (String) xpath.evaluate( "box_art/@large", node, XPathConstants.STRING ); %> <tr><table><tr align="center"> <img src="<%=sImage&>"/><br /> <%=sTitle%><br />Added To Queue<br /></tr> </table></tr> <%   } } else { %>   Operation failed <% } %> </table></body></html>

Since adding a title to a subscriber's instant-watch queue requires the subscriber's permission, this example begins by retrieving the subscriber's data and OAuth access tokens. Then, the code forms the request for the POST operation, starting with the resource to add a title to the instant-watch queue: /users/user_id/queues/instant. To this, it concatenates the reference to the title parameter (title_ref) plus its value (the URL link to the title), the HTTP method (POST), and the user access token. When the code builds the request, it submits the request to the server.

When the response is received, the code checks for success or failure. If successful, then it displays the updated instant-watch queue items.

Performing Basic Application Tasks

Most likely, you will begin your application design with a set of tasks or operations that you want to perform. These tasks might include:

looking up a specific movie or TV show title in the Netflix instant-watch title catalog
finding other titles starring the same actor(s)
retrieving details about catalog titles
accessing RSS feeds
allowing the subscriber to manipulate titles in her instant-watch queue, and updating other user data

The table below shows some basic application tasks and which Netflix API resources you use to accomplish these tasks. It shows you where to start with the API and briefly describes how to use the resources. You need to know how to perform the necessary OAuth authentication steps, since authentication is required in order to access some resources, and you should be familiar with the Netflix REST API Conventions. Refer to the API Reference for a more complete description of each resource.

Note: The root for Netflix API is http://api.netflix.com. When you form the URLs for the requests to the different API resources, be sure to include the complete location. For example, the correct URL for the /catalog/titles resource is http://api.netflix.com/catalog/titles.

How To…	Use…
Search for catalog titles	`catalog/titles` returns instant-watch catalog title URLs (whose format is `catalog/titles/12345678`) that you can use in subsequent requests, such as queries for title details or requests to add titles to the instant-watch queue. You use the search API resources as a source of titles that you then use with other API resources. Use the title expansion parameter `expand=value` to retrieve title details or links to details inline. The parameter values are title detail varieties separated by commas, such as "`cast`" and "`directors`". (See Title Expansion for information on title expansion.) `catalog/titles/autocomplete` facilitates autocompletion of a title search. As the user enters a title to search for, this resource returns a list of matching search terms. This allows you to give the user a list of suggested matches for search terms. The user can select from this list or continue typing to narrow the list choices.
Retrieve title details	`catalog/titles/12345678` and all `catalog/titles` movie and television series seasons subresources (see Retrieving Title Details.) Use the title expansion parameter `expand=value` to retrieve title details or links to details inline. The parameter values are title detail varieties separated by commas, such as "`cast`" and "`directors`". Title expansion brings the title details that are referenced by the parameter value(s) into the response itself. (See Title Expansion for information on title expansion.)
Retrieve similar titles	`catalog/titles/12345678/similars`
Retrieve details about people associated with a title	Use the title expansion `expand=cast,directors` in `catalog/titles` search to retrieve links to details about cast members and directors inline. (See Title Expansion for information on title expansion.) Use the `catalog/people/personID` link entry included in the title response to retrieve details about specific individuals associated with the title.
Access Netflix resources on behalf of a subscriber	See the Authentication Overview page and the OAuth API. Generally, a subscriber must log in for you to gain access to the user identifier, which you need for all other subscriber-related tasks. The subscriber may not have to log in if they are cookied, but they still have to authorize your application to access the service on their behalf. Authorization is necessary for you to gain access to the subscriber's user identifier, access token, and token secret.
Get subscriber details (name, associated queues, and preferred formats)	`users/userID`
Access an Atom feed for a subscriber	`users/userID/feeds` returns links (URLs) with the feeds available for the user. The necessary security tokens are embedded within these links, so you can access these feeds without any OAuth calls.
Determine a subscriber's rental options for catalog titles	`users/userID/title_states` returns the relationship between a subscriber and a list of specific titles, along with the preferred action to play the title or to add the title to the subscriber's instant-watch queue.
Get information about a subscriber's queue	`users/userID/queues` and subresources (see Managing Queues). Use these to retrieve instant-watch queue details (current titles, positions within queue, availability). Retrieve queue details with these resources using the HTTP `GET` method.
Manage titles in a subscriber's queue	Use `users/userID/queues/instant` with the HTTP `POST` method to update the instant-watch queue (add titles or move titles to different positions in the queue). When you retrieve queue details using these resources with the GET method, the response includes the URL of the queue entry for each item in the queue. You can submit these resource URLs with the `POST` or `DELETE` methods to update (add, move, or remove) the queue entries. Delete titles from a queue using these subresources with the HTTP `DELETE` method (see Updating a Queue): `users/userID/queues/instant/available/entryID` `users/userID/queues/instant/saved/entryID`
Retrieve a subscriber's viewing history details	`users/userID/rental_history` and subresources (see Managing Rental History). Retrieve a list of titles that were instant-watched by a subscriber.
Retrieve a subscriber's actual ratings of titles and Netflix's prediction of the subscriber's ratings	`users/userID/ratings/title` returns the actual and predicted ratings for the subscriber. (See User Title Ratings.) `users/userID/ratings/title/actual` returns the actual rating given by a subscriber for the specified title(s). `users/userID/ratings/title/predicted` returns predicted ratings for the subscribr for the specified title(s).
Create a rating of a title for a subscriber and updating a subscriber's existing rating of a title	`users/userID/ratings/title/actual` used with the HTTP `POST` method lets you create a subscriber rating for an individual title. Returns the new rating in the URL `users/userID/ratings/title/actual/ratingID`. Use `users/userID/ratings/title/actual/ratingID` with the HTTP PUT method to update an existing rating.
Retrieve title recommendations	`users/userID/recommendations` returns recommendations of other catalog titles for this subscriber based on the subscriber's rating and rental history.
Retrieve a complete index of all Netflix instant-watch catalog titles	`catalog/titles/index` This resource is intended for use by partners who have their own movie and television catalogs and wish to find matching titles in the Netflix instant-watch catalog.