- Up: Introduction to Netflix API Documentation
- Next: Netflix REST API Reference
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
- Basic Terminology
- Organization of the Netflix Resources
- Handling Resource Requests and Responses
- Understanding Resources
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:
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:
<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:
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.
- A Title is a movie or television program that is potentially available for instant-watch streaming.
- 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.
- 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.
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/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:
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:
episodes(series and seasons only)
This section covers how to form resource requests and how to work with the resulting responses.
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
GETrequest 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
PUTHTTP verb in a similar manner to update a Netflix resource, such as some information about a subscriber, and the
DELETEverb to delete entries.
- If you are creating a brand new resource, use the HTTP
POSTmethod on a parent resource (if you have the URL to a resource that you want to update, use the
PUTmethod; if you do not have the URL, because the resource doesn't yet exist, do a
POSTon the parent resource). You may also override the HTTP
POSTmethod 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
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:
...extract the URL resource for the movie and use it with the
GET method to retrieve a record associated with the specific movie.
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
DELETE, or pass a
method parameter whose value you set to the HTTP method you want to use (
There are different types of resource responses. Responses also include status codes, which can be helpful for debugging purposes.
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.
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.
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
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|
||a standard HTTP status code that indicates success or failure|
||an additional numeric code if the standard HTTP status code is not sufficient for effective error processing (optional)|
||a string providing details on the request processing error (optional)|
||a list of resource links for all resources that were created as a result of a POST request (optional)|
||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:
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:
<message>Query param start_index out of bounds.</message>
In response to a successful
POST request the Netflix API might generate a response with a status like the following:
title="The Larry Sanders Show: Season 1: Disc 1"/>
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:
<message>Only some of the titles in the series or disc set could be added.</message>
The HTTP standard status codes and subcodes common to all resources are listed in HTTP Status Codes.
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.
<link> element describes relationships between resources. The
<link> element includes the following information:
hrefattribute that contains the URL of the linked-to resource
rel(related) attribute that indicates the type of the relationship between the linked resources
titleattribute, which is a human-readable label for the link (for example, a
titleentry might be "episodes" or "cast")
Here is an example of a
<link href="http://api-public.netflix.com/catalog/titles/series/70023522/episodes" rel="http://schemas.netflix.com/catalog/programs" title="episodes"/>
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.
<category> element has three attributes:
- The value of the
schemeattribute is a URL that describes the type of category. It is a resource itself, listing all possible values for the category.
termattribute adds the description of the selected value from the category's designated
labelattribute is a human-readable label for the category value.
<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
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:
For example, if the ETag value was "
xyzzy", the above code would look as follows:
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
PUT requests. To do so, include an
If-Match header and pass the ETag value from a previous response, as follows:
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:
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:
Use of the version parameter is optional. If you do not specify it in a request, the default is version 1.0.
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:
- 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.
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">…
<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"/>
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
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".)
- short synopsis
- screen formats
- languages and audio
- bonus materials
- queue item