Netflix REST API Conventions

Netflix API 1.5 Programmer’s Guide: API Conventions

The Netflix API 1.5 (sometimes also called the "WebAPI" or "REST API") is a RESTful, resource-oriented, open-standards architecture that developers can use to work with Netflix-maintained media metadata and subscriber information. You can use just about any web language to access the API so long as it can make HTTP requests and parse XML responses. This page covers the following topics:

REST API Overview

The Netflix API adheres to REST standards. You reference particular resources by means of the URL path (the part of the URL after the host name). The response from the Netflix API includes <link>s that tie together related resources. You use standard HTTP verbs to access the Netflix API with different methods. For example, if you wanted to retrieve information about a particular Netflix subscriber, you might construct the following HTTP request:

GET /users/user_id

Since you want to retrieve information, you use the HTTP GET verb. The path /users/user_id describes the resource you use to access information about a specific subscriber. The response that comes back not only includes information about the particular subscriber (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 subscriber's instant-watch queue. Each piece of data in the response is identified by an XML tag. For example, the following illustrates one possible response:

<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-public.netflix.com/users/T1PambOVJXcoWzNRQEyacp76BnRn0TIJdxKGyklbY0srg-/queues" rel="http://schemas.netflix.com/queues" title="queues"/>

You access the Netflix API by using standard REST conventions. 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 page describes the general API conventions and protocols. The Netflix REST API Reference page contains detailed descriptions of each individual Netflix API 1.5 resource, including how the resource works with the four HTTP verbs. You access all Netflix API resources by sending requests (either HTTP or HTTPS) to api-public.netflix.com unless otherwise noted.

In addition to the API, you can also use the JavaScript API to access the Netflix catalog. You can use the JavaScript API to add a subset of the Netflix user experience to your web pages, as described on the JavaScript API Reference page. You can use that API to render the Netflix Add and Play buttons on your own site. This page does not describe that API, but the Netflix API.

Basic Terminology

Title
A Title is a movie or television program that is potentially available for instant-watch streaming.
Catalog
The Catalog is Netflix's entire collection of instant-watch titles. The catalog holds all information about each title in the collection. Used generically, the catalog refers to the collection of titles and information about them. In the context of the Netflix API, "Catalog" specifies the name of the resource that you use to retrieve information about titles.
Users
The Users resource is the collection of all Netflix users or subscribers. Each user is a resource with which you can access and update user information.

Organization of the Netflix Resources

The API is divided into two resource groups: Catalog and Users (there is also another resource that you use to get the credentials you must use to sign your Netflix REST API requests).

The Catalog resources are Netflix data about titles, actors, directors, and related items. For example, you might use these resources to search for titles of movies in which certain actors appear. 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.

The Users resources concern Netflix subscribers, such as a subscriber's instant-watch queue, ratings, and so forth. (Users refers to the top level resource, /users , beneath which are the resources for each subscriber. Thus, the resource /users/user_id/recommendations returns a list of titles that Netflix believes the subscriber user_id will like.) You can retrieve information from a Users resource, such as a list of a particular subscriber's recently-viewed titles, to then retrieve information about those titles with the Catalog resources. These Users resources are also how your web application accesses the Netflix service on behalf of a subscriber.

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 subscriber's instant-watch queue or you may be adding or updating ratings for that subscriber.

Some resources, such as Catalog, are actually only collections of 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 response from other resources. In the response, the Netflix API replaces title with one of the title types: movie, series, season, program, or disc. Some other resources also make Atom feeds available to you.

The following list shows the hierarchy of resources and their relationships, as well as which resources are collections of links only, and for which resources feeds are available:

  • http://api-public.netflix.com/
    • catalog/ (collection only)
      • people/person_id
        • filmography
      • titles
        • streaming
        • dvd
        • autocomplete
        • [movies|series|series/series_ID/seasons|programs|discs]/title_ID/
          • synopsis
          • format_availability
          • bonus_materials
          • awards
          • cast
          • directors
          • screen_formats
          • episodes (series and seasons only)
          • seasons (series only)
          • similars
          • languages_and_audio
    • users/current
    • users/user_id
      • feeds
      • queues/ (collection only)
        • instant (feed available)
          • saved (feed available)
          • available (feed available)
      • title_states
      • recommendations (feed available)
      • ratings/ (collection only)
        • title
          • actual (feed available)
          • predicted (feed available)
      • lists

Resource Requests and Responses

This section covers how to form resource requests and how to work with the resulting responses.

How to Form Requests

All Netflix API requests are made by the use of an HTTP verb:

  • In most cases, you retrieve information from Netflix by having your client make an HTTP GET request for the URL that identifies the specific resource you are requesting. You specify any parameters for the resource using name/value pairs. In most cases, you need to sign your request with a particular parameter that you generate according to the process described in Authentication Overview.
  • Use the PUT HTTP verb in a similar manner to update a Netflix resource, such as some information about a subscriber, and the DELETE verb to delete entries.
  • If you are creating a brand new resource, use the HTTP POST method on a parent resource (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 yet exist, do a POST on the parent resource). You may also override the HTTP POST method to simulate the other three methods in some cases (this is described in greater detail below).

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

http://api-public.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 from the response:

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

...extract the URL resource for the movie and use it with the GET method to retrieve a record associated with the specific movie.

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

If your client does not support all four HTTP verbs, or if your GET request exceeds the URL size limits, you can use the HTTP POST verb instead. When you use POST in this way, either set the X-HTTP-Method-Override header to GET, PUT, or DELETE, or pass a method parameter whose value you set to the HTTP method you want to use (GET, PUT, or DELETE).

Resource Responses

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

Format of the Response

The Netflix REST API resources typically return data formatted as "plain old XML" (POX). 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.

The API will automatically return responses compressed in gzip format if you supply the Accept-Encoding: gzip HTTP header in your request.

Types of Responses

The response you receive from a successful GET request varies according to the resource. You can expect different fields of information in the response depending on which resource you requested.

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

Response Status Codes

The Netflix API returns standard HTTP header information with all of its responses. This header information indicates:

  • the HTTP response status code
  • an ETag value (you will read more about ETags further on)
  • resource link locations of any resources that were created as a result of the request

The Netflix API also returns this same information in the response body itself, because not all clients can access this header information and because the information found in the header may not be sufficiently detailed for all response types. All responses (successful or not) for all POST, PUT, and DELETE requests, and all non-successful GET requests, include a status response type in the response body, in the same format.

This status information, and particularly the message text that the Netflix API may include with it when a processing error occurs, may be useful to you for debugging purposes. A status response may include the following elements:

Status Response Element Description
status_code a standard HTTP status code that indicates success or failure
sub_code an additional numeric code 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 a list of resource links for all resources that were 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)

A basic status response might simply return just the status code, like in the following example:

<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 Netflix API might respond with a status response like the following:

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

In response to a successful POST request the Netflix API might generate a response with a status like the following:

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

In response to a POST request to add items to a subscriber's instant-watch queue that the Netflix API completed with only partial success, it might return a status response like the following:

<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>

The HTTP standard status codes and subcodes common to all resources are listed in HTTP Status Codes.

Understanding Resources

Most Netflix API resources maintain relationships to other resources. In addition, resources may be grouped by common characteristics, or categories. This section covers the XML data that you will see in responses that describe related resources.

Resource Relationships

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

  • an href attribute that contains the URL of the linked-to resource
  • a rel (related) attribute that indicates the type of the relationship between the linked resources
  • a title attribute, 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-public.netflix.com/catalog/titles/series/70023522/episodes" rel="http://schemas.netflix.com/catalog/programs" title="episodes"/>

Categories of Resources

Categories provide information about certain groupings a particular resource belongs to. For example, a category might indicate the media formats a title is available in. The Netflix API indicates what categories a resource belongs to by including the Atom-style <category> element in its responses to resource requests.

The <category> element has three attributes: scheme, term, and label:

  • The value of the scheme attribute is a URL that 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 <category> element below indicates media that is immediately available to play. If the Netflix API returned this category in the response for a request for a particular title, that would indicate that the specified title is one that subscribers can immediately play (as opposed to one that won't be available to play until a future date).

<category scheme="http://api-public.netflix.com/queues/availablity" term="available_now" label="Available Now"/>

Resource Cache and Concurrency Control

HTTP entity tags, or ETags, help ensure caching and concurrency control for API resources. When an ETag is associated with a resource, you can use the ETag value to ask the Netflix API if your version of a resource is the latest version or whether it has changed since you last retrieved it. When the Netflix API responds to an HTTP POST or PUT request to a resource that accepts such requests, it always returns an ETag in the ETag HTTP header and an etag element in its response (both with the same value).

To implement cache control by using ETags, you need to query the server to see if the previously-returned, cached resource still matches the state of the current resource on the server. To do so, you include an If-None-Match header and set its value to the value of the ETag that accompanied your cached resource value when you retrieved it from the Netflix API. 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 this request matches the ETag value of the current resource on the server, the Netflix API replies with 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 Netflix API returns a resource response with a new ETag value.

Similarly, you can use ETags to implement concurrency control for resources that support such control and that use POST and PUT requests. To do so, 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).

For resources that support concurrency control you can also use the etag parameter to pass the ETag value as part of the resource request rather than as a separate header metadata item, like this:

http://api-public.netflix.com/&etag=etag_value&

Using Specific API Versions

Netflix supports multiple versions of the API and allows you to use them concurrently. Set the v parameter within a request if you need to access a specific version of the API. For example, to invoke version 1.5, you might request a catalog/titles resource as follows:

http://api-public.netflix.com/catalog/titles/series/70023522?v=1.5

Use of the version parameter is optional. If you do not specify it in a request, the default is version 1.0.

Using Title Expansion to Retrieve Title Details

You can use expansion to retrieve particular details about titles in the Netflix catalog in the same response you get when you request a list of titles, for instance in a search or in the retrieval of a queue. By using expansion, you avoid the process of retrieving the list and then making additional calls to retrieve details about each item in the list. This is more efficient and helps you avoid running up against the limits of your request quota.

One of the principal resource types in the API is a catalog title resource. A title refers either to programming that can be rented as a disc or watched instantly, or to a collection of rentable and/or viewable items. Examples of titles are:

  • movies
  • television programs
  • groups of related titles, such as:
    • a television series
    • a television series season
    • 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. You can expand the title response format so you can access details about each title without having to make additional title resource queries on the individual titles in the response. For example, you can query the catalog for titles that match some criteria and at the same time ask the Netflix API to extend its response format so that it includes additional details about each title other than those in the default response format.

Title Expansion

You retrieve additional information about titles in this way by means of title (or link) expansion. 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/seasons/episodes, and cast. By using expansion, your application can retrieve many of a title's linked resources at the same time that it retrieves the basic title information.

When you do a query without title expansion, some of the elements you recieve in the response are linked resources. These appear as <link>s in the response. For example, you might see this <link> in the response:

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

When you request expansion of a particular linked resource, the Netflix API expands the link to include its contents inline in the response (though if the linked resource itself represents a collection of other resources, it is partially, not recursively, expanded into a list of resource links). For example, with 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-public.netflix.com/catalog/titles/series/70023522/cast" rel="http://schemas.netflix.com/catalog/people" title="cast">
 <cast>
  <link href="http://api-public.netflix.com/catalog/people/30011713" rel="http://schemas.netflix.com/catalog/person" title="Steve Carell"/>
  <link href="http://api-public.netflix.com/catalog/people/30014922" rel="http://schemas.netflix.com/catalog/person" title="John Krasinski"/>
  <link href="http://api-public.netflix.com/catalog/people/20047634" rel="http://schemas.netflix.com/catalog/person" title="Jenna Fischer"/>
  <link href="http://api-public.netflix.com/catalog/people/20028105" rel="http://schemas.netflix.com/catalog/person" title="Rainn Wilson"/>
  …
 </cast>
</link>

You can request expansion from the Netflix API for all resource response items that include title data, such as:

  • a queue item
  • a rating
  • a recommendation
  • a viewing history item

Using Title Expansion

To request expansion, set the expand parameter in your resource request. You need to set the expand parameter to one or more <link> titles that are appropriate to the particular request. For example, to expand the cast and directors for titles in a television series, you form the request as follows

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

Netflix API 1.5 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, except with any spaces percent-encoded to "%20".)

  • synopsis
  • short synopsis
  • formats
  • screen formats
  • cast
  • directors
  • languages and audio
  • seasons
  • episodes
  • discs
  • similars
  • filmography
  • awards
  • bonus materials
  • person
  • queue item