Common REST API Tasks

This section provides some guidelines and examples for using the APIs. It covers the following topics:

Using the API.: A general description of how to use the Netflix REST 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 queue.
Performing Basic Application Tasks.: Provides a list of common tasks and the API resource you might use to accomplish these tasks.

Using the API

This section describes in general terms the steps to use the Netflix REST API.

Get the proper authorization. Do any necessary user login steps and OAuth authorization.
Set up parameters. Set up any parameter values that you may be passing to the API (for the API resources that take parameters). You may need to prompt the user to enter values. For example, to search for matching catalog titles, you may need to get a partial title string from the user and then set up the search term value.
Build the request to the API. The request consists of the full URL to the API itself, plus the name of any parameters and their values.
Invoke the request. Depending on the request, you invoke it with the appropriate HTTP method: GET, PUT, DELETE, or POST.
Get the response and parse it for the data you need. If you are retrieving information, parse the response 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 as links to other resources.
Use the response data to do further operations. You can use the links (which are URLs) within a response in other requests. That is, you can pass these links or portions of them to other API resources to retrieve or update the data they reference. For example, if you retrieve details about a title, the response includes the URL for box 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 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 the Netflix API. The samples show a simple search for a catalog title and adding a title to a user's queue.

Search for Title Example

The example below uses the catalog/titles API to search for 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.)

Here's what is happening in the above example. The code prompts the user to enter a title, then builds a request to search the catalog for matches on the term entered by the user. The request consists of the API'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, making it easier to handle changes to the API root address.)

The code adds the parameter name and value to the end API 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 the request is constructed, 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 API returns a response with the representation catalog_titles . Each title entry in the returned document is delimited within a catalog_title tag, 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 can be used to pull in more information for display or passed to other API operations. The code evaluates the tags in the response and displays the title and the box art image.

Add a Title to a User's Queue Example

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

Since adding a title to a user's queue requires the user's permission to access the queue and the proper authorization, the example begins by retrieving the user's data and OAuth access tokens. Then, the code forms the request for the POST operation, starting with the API to add a title to a disc queue: /users/user_id/queues/disc. 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. Once the request is built, the code submits it to the server.

When the response is received, the code checks for success or failure. If successful, then it displays the updated 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 television title in the Netflix catalog
Finding other titles of the same genre or starring the same actor(s)
Retrieving details about catalog titles
Accessing RSS feeds
Allowing the user to manipulate titles in her queues, such as selecting and adding titles to an instant watch queue, and updating other user data

The table below shows the basic application tasks and the Netflix API resources you use to accomplish these tasks. It provides an orientation of 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 may be required for some tasks, and you should be familiar with the Netflix API programming conventions. (Netflix REST API Conventions.) Refer to the API reference section for a more complete description of each operation.

Note: The root for the 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 API /catalog/titles is http://api.netflix.com/catalog/titles.

How To ...	Use ...
Search for catalog titles	catalog/titles returns catalog title URLs (whose format is catalog/titles/12345678) which can be used in subsequent requests, such as queries for title details or requests to add titles to a 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 categories separated by commas, such as cast and directors. (See Understanding Resources for information on title expansion.) catalog/titles/autocomplete incorporates automatic completion in the title search. As the user enters a title to search for, lists of search terms matching the partial search text are returned. 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 categories 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.
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. (Also see Understanding Resources.) 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 user	Security. section and OAuth API. Generally, a user must login for you to gain access to the user identifier, which you need for all other user-related tasks. However, the user may not have to login if they are cookied, but they still have to authorize the application to access the service on their behalf. Authorization is necessary for you to gain access to the user identifier, access token, and token secret.
Get user details (name, associated queues, and preferred disc formats)	users/userID
Access an RSS feed for a user	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 user's viewing options/queues and the availability of specific titles, along with the preferred action to add the title to the user's queue.
Get information about a user's queue	users/userID/queues and subresources (see Managing Queues). Used for retrieving queue details (current titles, positions within queue, availability). Retrieve queue details with these API resources using the HTTP GET method.
Manage titles in a user's queue	users/userID/queues/instant and users/userID/queues/disc used with the HTTP POST method let you update the queue (add titles or move within the queue). When you retrieve queue details using these API resources with the GET method, the response includes the URL of the queue entry for each item in the queue. You can pass these URLs to these resources 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 users/userID/queues/disc/available/entryID users/userID/queues/disc/saved/entryID
Determine titles shipped to a user but not yet returned to Netflix	users/userID/at_home
Retrieve a user's rental history details	users/userID/rental_history and subresources (see Managing Rental History). Retrieve a list of discs shipped to a user, discs returned to Netflix, or titles that were watched instantly.
Retrieve a user's actual ratings of titles and Netflix's prediction of the user's ratings	users/userID/ratings/title returns the actual and predicted ratings for the user. (See User Title Ratings.) users/userID/ratings/title/actual returns the actual rating given by a user for the specified title(s). users/userID/ratings/title/predicted returns predicted ratings for the user for the specified title(s).
Create a rating of a title for a user and updating a user's existing rating of a title	users/userID/ratings/title/actual used with the HTTP POST method lets you create a user 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 reviews of titles	users/userID/reviews returns the user’s reviews or a specific review for the specified title(s).
Retrieve title recommendations	users/userID/recommendations returns recommendations of other catalog titles for this user based on the user's rating and rental history.
Retrieve an index of all Netflix 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 catalog.