REST API Conventions

The Netflix Web API is a RESTful, resource-oriented architecture that makes an open standards API available to developers. This means that you can use just about any web language to access the API in your web applications. The only requirements for the language you use are that it has the ability to make HTTP requests and can parse XML responses. This section covers the following topics:


REST API Overview

The Netflix REST API adheres to REST web standards. Designed to be resource centric, the API keeps the data references for resources in the URL path, to the right of the host name, and uses links to tie together related resources. Method information goes into the standard HTTP verbs. For example, if you were interested in retrieving information about a particular Netflix user, you might construct the following HTTP request:

GET /users/my-user-id
 ...

Since you want to retrieve information, you use the HTTP GET verb. The path /users/ my-user-id references the resource for information about a specific user. The response that comes back not only includes information about the particular user (such as first and last name, preferred viewing formats, and so forth), it also may include links or references that you can use to retrieve more information, such as links to the user's queues. Each piece of data is identified by an XML tag. For example, the following illustrates the data a response might include:

<first_name>Jane</first_name>
<last_name>Smith</last_name>
<can_instant_watch>true</can_instant_watch>
<preferred_formats>...</preferred_formats>
...
<link href="http://api.netflix.com/users/
        T1PambOVJXcoWzNRQEyacp76BnRn0TIJdxKGyklbY0srg-/queues" 
rel="http://schemas.netflix.com/queues" title="queues"></link>
...

You access Netflix web functionality using a programmatic REST API. Each API function or method follows standard REST conventions. That is, each API method:

  • Is modeled as a resource
  • Has links to its children and any related resources
  • Is invoked using one of the HTTP verbs: POST, GET, PUT, and DELETE. These HTTP verbs directly correlate with the database CRUD (create, read, update, and delete) operations.

This section describes the general API conventions and protocols. The reference section contains detailed descriptions for each API resource, including how the resource works with the four HTTP verbs. Keep in mind that all API resources are accessible at api.netflix.com unless otherwise noted.

In addition to the REST API, you can also use a JavaScript API to access the Netflix catalog. The JavaScript API is a simpler but less secure API that can be used to access Netflix user experiences from your own web pages. You can this API to render the Netflix Add and Play buttons to your own site.

Basic Terminology

This section defines some of the basic terminology.

  • Title: A title is a movie or a television program (both of which are collectively referred to as media) that is delivered either as a DVD disc or that can be watched instantly.
  • Catalog resources: The entire collection of titles (or media) available for rent or to watch instantly. The catalog holds all information about each title in the collection. Used in one sense, the catalog refers to the collection of media titles and information. Catalog also specifies the name of the resource API for retrieving information about titles.
  • Users resources: The collection of all Netflix users or subscribers. Each user is a resource for accessing and updating user information.

Organization of the Netflix Resources

The API resources are divided into two groups: Catalog and Users. These resources model the way that media titles (movies and television shows) and user data (along with access to the Netflix service on a user's behalf) are stored. The Catalog resources pertain to the Netflix data holding people and titles and related items. For example, you might use these resources to search for titles of movies in which certain actors appear.

The Users resources pertain to information specific to Netflix subscribers, such as a user's queue, rental history, personal ratings, and so forth. (Users refers to the top level resource, /users , beneath which are the resources for each user. Thus, the resource /users/<user>/at_home returns the discs that the subscriber identified by the id <user> currently has at home.) You can retrieve information from a Users resource, such as a particular user's recently viewed titles, to retrieve related titles with the Catalog resources. These user resources are also how your web application accesses the Netflix service on behalf of the user.

You use the Catalog resource and its subordinate resources to search for and retrieve information from the Netflix catalog; you will not be writing to the catalog. For the users portion of the Netflix data, most of your interaction will involve retrieving information. However, you may also be using the Users resources to do some write operations. For example, you might be adding or updating entries to a user's queue or you may be adding or updating ratings for that user.

Some of the resources, such as catalog, are actually only links to other resources. That is, you do not retrieve information by doing a GET operation on /catalog ; instead, you do the GET operation on a resource that catalog links to, such as /catalog/titles or /catalog/people . The /catalog/titles/<title> resource is returned to you in the response when you do a catalog or index search for titles, or as a link in a responses from other resources. In the response, <title> is replaced with one of the title types: movie, series, season, program, or disc. Other resources also have feeds available.

The following diagrams show the organization of the resources and their relationships. The diagrams note the entries that have no data other than links to child resources. They also indicate the resources for which feeds are available. The first figure shows the top level of resources.

Top Level Resources

The following figure shows all the resources within the titles hierarchy.


Titles Resource Hierarchy

The next figure shows the User resource hierarchy. Note that a number of the user resources have feeds available.

User Resources

Handling Resource Requests and Responses

This section covers the basics for handling resource requests and the resulting responses.

Forming Requests

In most cases, you retrieve information from Netflix by having your client invoke an HTTP GET request and setting the request to the Uniform Resource Identifier (URI) of the specific REST API. (The URI acts as the identifier of the REST resource.) You specify any parameters for the resource using name/value pairs: the name of the parameter and a value for that parameter. You use the PUT HTTP verb in a similar manner to update the Netflix resource, such as some stored information about a user, and the DELETE verb to delete entries. Use the HTTP POST method on a parent resource to create a child resource.

Here's another way to determine whether to use the HTTP PUT or POST method. If you have the URL to a resource that you want to update, use the PUT method. If you do not have the URL (because the resource doesn't exist) do a POST on the parent resource.

For example, to search for movie titles in the Netflix catalog, you might use this resource with the GET method:

http://api.netflix.com/catalog/titles

You can get details about a specific movie by using the HTTP link returned by the catalog/titles resource as a resource itself. For example, you might take this link:

<link href="http://api.netflix.com/catalog/titles/movies/17985448 ... /link>

extract the URL resource for the movie and use it with the GET method.

http://api.netflix.com/catalog/titles/movies/17985448

However, your client may not support all four HTTP verbs, or your GET request may exceed the URL size limits. If that is the case, you can use the HTTP POST verb instead. When using POST, set the X-HTTP-Method-Override header to GET, PUT, or DELETE. You can also use HTTP POST by passing the POST verb a method parameter in the API request that is set to the HTTP method of choice (GET, PUT, or DELETE).

Resource Responses

There are different types of resource responses, and responses may have different formats. Responses also include status codes, which can be helpful for debugging purposes.

Format of the Response

The REST API resources return the output data formatted by default as vanilla XML data, or what is referred to as "plain old XML" (POX). Feed content is returned in Atom format.

(Currently, the Atom format is supported for feeds only. In the future, Atom may be supported for all responses.)

Note, too, that the format of the response determines how any date and time fields within the response are expressed. Responses in POX format show date and time fields in Unix format, which is the number of seconds since epoch. Responses in Atom format use a format dictated by the standard, RFC 3339 format, for date and time fields.

In the near future, the API will automatically return the API responses zipped up, in gzip format, if you supply the gzip Accept-Encoding parameter in the HTTP header of your request. Since the server currently ignores this header directive, you can safely include it in your application now. When this feature is available in the future, you will immediately gain this performance benefit.

Types of Responses

The response you receive from a successful GET request varies according to the resource. That is, you can expect different fields of information depending on the resource you invoked.

Each type of response is identified by a resource representation. For example, if you use the resource catalog/titles to retrieve a list of titles, the XML response includes the <catalog_titles> resource representation tag to indicate the returned title data.

Response Status Codes

All resources return standard HTTP header information. This header information indicates:

  • Response status code
  • etag values
  • Locations of any newly created resources

The same information is also returned in the response body, since not all clients can access this header information. Also, the information found in the header may not be sufficiently detailed for all response types. Thus, all responses (successful or not) for all POST, PUT, and DELETE methods, along with all non-successful GET responses, include a status response type in the response body with the same response format.

The status information, and particularly the message text that may be included when a processing error occurs, is useful for debugging purposes.

The response format includes the following elements:

 

Status Response Element

Description

status_code

A standard HTTP status code indicating success or failure.

sub_code

An additional numeric code that is provided if the standard HTTP status code is not sufficient for effective error processing. (Optional)

message

A string providing details on the request processing error. (Optional)

resources_created

List of resource links for all resources created as a result of a POST request. (Optional)

etag

A new etag value after a POST operation. Returned only for resources that support etags and concurrency control. (Optional)

Other element content

Additional XML elements that provide further details about the resource response. (Optional)

For example, a basic status response might simply return just the status code, as follows:

<status>
        <status_code>200</status_code>
 </status>

In the case of a request error for which an additional numeric code is needed along with a message, the status response might be:

<status>
        <status_code>400</status_code>
    <sub_code>120</sub_code>
  <message>Query param start_index out of bounds.</message>
 </status>

A successful POST request might generate a response with a status such as the following:

<status>
        <status_code>201</status_code>
    <resources_created>
             <link href="http://api.netflix.com/catalog/titles/discs/60022255" 
                         rel="http://schemas.netflix.com/title" 
                       title= The Larry Sanders Show: Season 1: Disc 1</link>
  </resources_created> 
 </status>

A POST request to add items to a user's queue that had only partial success might return a response with a status response type and element values as shown below. In this case, the response includes values for the optional elements in status.

<status>
        <status_code>201</status_code>
    <sub_code>640</sub_code>
  <message>Only some of the titles in the series or disc set could be added.</message>
      <etag>657707210550</etag>
         <resources_created>
             <queue_item>
            ...
   </resources_created>
    <failed_title_refs>...</failed_title_refs>
        <already_in_queue>...</already_in_queue>
 </status>

Note that the HTTP standard status codes and the subcodes common to all resources are listed in one table: Status Codes Common to All Resources..


Understanding Resources

Most resources maintain relationships to other resources, including relationships to children of a resource or just a related resource. In addition, resources may be grouped by common characteristics, or categories. This section covers the response XML data that describes particular resources.

Resource Relationships

An Atom-style link element describes relationships between resources. The link element includes the following information:

  • An href attribute, which contains the URL of the linked to resource
  • A rel (related) entry, which indicates the type of the relationship between the linked resources. For example, for a list of titles related to a television series, the rel entry would be episodes .
  • A title entry, which is a human-readable label for the link. For example, a title entry might be "episodes" or "cast".

Here is an example of a link element:

<link href="http://api.netflix.com/catalog/titles/series/70023522/episodes" 
rel="http://schemas.netflix.com/catalog/programs" title="episodes"/>

Categories of Resources

Categories provide type information about a resource. Values for categories may be applied programmatically. For example, a category might indicate the genres or media formats of the resource. Categories are applied to resources using the Atom-style category element.

The category element has two attributes: scheme and label . The scheme attribute is a URL which describes the type of category. It is a resource itself, listing all possible values for the category. The term attribute adds the description of the selected value from the category's designated scheme . The label attribute is a human-readable label for the category value. The first example category element below indicates television sitcoms from the genres category, while the second example indicates media that is immediately available on a queue.

<category scheme="http://api.netflix.com/catalog/genres" term="tv_sitcoms" label="TV Sitcoms"/>
 ...
 <category scheme="http://api.netflix.com/queues/availablity" term="available_now" 
 label="Available Now"></category>

Keep in mind that you can query any category scheme to determine its possible values. To do this query, you might use a URL similar to the following:

  1. http://api.netflix.com/categories/genres  

Resource Cache and Concurrency Control

HTTP entity tags, which are referred to as ETags , enable caching and concurrency control for API resources. When associated to a resource, the ETag value indicates the current state of the resource. ETags are always returned in the ETag HTTP header within the resource request for all resources. Resources that support the HTTP POST or PUT methods also return these entity tag values as etag elements in their responses.

To use ETags for cache control, you need to query the server to see if the previously returned resource still matches the current resource on the server. To do so, you include an If-None-Match header and pass the ETag value that was returned from the previous response. For example, you might have the following:

If-None-Match: "<etag value>"

For example, if the etag value was "xyzzy ", the above code would look as follows:

If-None-Match: "xyzzy"

If the ETag value that you pass in the request matches the ETag value of the current resource on the server, you get back an HTTP response code of 304 (Not Modified), indicating that the resource on the server has not changed. However, if the ETag value you pass in does not match the ETag value for the resource on the server, then the resource response is returned with a new ETag value.

Similarly, you can use ETags for concurrency control for resources that support such control and use POST and PUT requests. Include an If-Match header and pass the ETag value from a previous response, as follows:

If-Match: "<etag value>"

The server accepts the request if the ETag value that you pass with the request matches that of the current resource on the server. However, if the two ETag values do not match, the server returns an HTTP response code of 412 (Precondition Failed).

As an alternative, keep in mind that resources that support concurrency control let you use the resource etag parameter. For these resources, you can pass the etag value as a parameter as part of the resource request rather than as a separate header metadata item. The resource description for the API documents using this parameter.

Using Specific API Versions

Netflix intends to support multiple versions (at a minimum, two versions) of the API and allows them to be used concurrently. Use the v parameter with a request to access a specific version of the API. For example, to invoke version 1.0, you might request the catalog/titles resource as follows:

http://api.netflix.com/catalog/titles/series/70023522?v=1.0

Use of the version parameter is optional. If not specified in a request, then by default the most recent, stable version of the API is used. At this time, the API only supports a version value of 1.0.

Using Title Expansion to Retrieve Title Details

One of the principal resource types in the API is a catalog title resource. As defined previously, a title refers to media that can be rented as a disc or watched instantly. A title may also represent a collection of other rentable and viewable titles. Examples of titles are:

  • Movies
  • Television programs
  • Groups of related titles, such as:
  • A television series
  • A television series seasons
  • A disc containing a subset of a television series season

Titles play a central role in many of the responses returned by resources. For example, queries such as title searches, queue entries, and ratings all return title-centric responses. By design, these response formats extend the title response format such that details about each title are readily accessible with no additional title resource queries on individual titles in the response. That is, you might query the catalog for titles that match some criteria. The response format includes basic information on each matching title, and a means to extend the response format to include further title details without having to separately query each title in the response.

What is Title Expansion

The ability to retrieve additional information about titles without separate queries is accomplished via title element or link expansion. Title element expansion takes advantage of the links between a title resource and its subresources. To illustrate, a title resource maintains links to such subresources as the title's synopsis, related series/season/episodes, and cast. Some applications may only want to retrieve the basic "top level" title information, while others may want details on cast, episodes, and so forth. By using title element expansion, an application can retrieve many of a title's linked resources at the same time that it retrieves the basic title information.

By using title element expansion, you can have the initial title query results include inline the content of some of the resources that are linked to the title. A query done without title expansion returns a set of data where some elements are linked resources. These appear as links in the response. For example, you might see this link in the response:

<link href="http://api.netflix.com/catalog/titles/series/70023522/cast" 
           rel="http://schemas.netflix.com/catalog/people" title="cast"/>

With title element expansion, a linked resource that represents a single resource is completely expanded inline. If the linked resource represents a collection of other resources, it is partially expanded into a list of resource links. For example, with title expansion, the single link to cast members shown above becomes, in the same response, a list of links to each individual cast member:

<link href="http://api.netflix.com/catalog/titles/series/70023522/cast" 
      rel="http://schemas.netflix.com/catalog/people" title="cast">
 <cast>
     <link href="http://api.netflix.com/catalog/people/30011713" 
           rel="http://schemas.netflix.com/catalog/person" title="Steve Carell"/>
     <link href="http://api.netflix.com/catalog/people/30014922" 
           rel="http://schemas.netflix.com/catalog/person" title="John Krasinski"/>
     <link href="http://api.netflix.com/catalog/people/20047634" 
           rel="http://schemas.netflix.com/catalog/person" title="Jenna Fischer"/>
     <link href="http://api.netflix.com/catalog/people/20028105" 
           rel="http://schemas.netflix.com/catalog/person" title="Rainn Wilson"/>
     ...
 </cast>
 </link>

You can use title link expansion with all resource response items that include title data, such as:

  • A queue item
  • A rating
  • A recommendation
  • Rental history item
  • Review

Using Title Expansion

You pass the expand parameter in the resource request to get a response back that expands the title link references. You need to set the expand parameter to one or more link titles. For example, to see the linked details for cast and directors for titles in a television series, you form the request as follows

http://api.netflix.com/catalog/titles/series/70023522?expand=cast,directors

The API supports title expansion for the following links. (Note that you specify these supported links using the link title, or link type name, exactly as shown below.)

  • synopsis
  • formats
  • screen formats
  • cast
  • directors
  • languages and audio
  • seasons
  • episodes
  • discs
  • similars
  • filmography

version 36 as of 6 months ago by bstearns

Comments

  1. Steve – 9 months ago

    The "Using Title Expansion" description indicates that the expansion parameter names should be comma seperated (expand=synopsis,cast,directors,episodes). The only I was able to get title expansion to work was by using space seperated values (expand=synopsis cast directors episodes).

    UPDATE::
    | We figured out the problem. Steve was using the .Net (C#) libraries which encode hex values to
    | lowercase (instead of the more traditional uppercase). If you are using .Net be sure to call
    | OAuthBase.URLEncode to encode your parameter values instead of the native UrlEncode().
    |
    | The OAuthBase library is available at http://oauth.googlecode.com/svn/code/csharp/.
    |
    | --jr@netflix

  2. thesubjective – 6 months ago

    Title Expansion is key for developers who find themselves repeatedly hitting their rate limits.

Please sign in to post a comment.