The Netflix OData Service (http://odata.netflix.com/Catalog) was updated this evening with some changes that might affect those of you that have written applications against it. All of the changes were additive (i.e. no properties were renamed or removed from the model), so it should be pretty simple to update your consumer code (famous last words).
There were three main changes made:
- The server-side paging for each of the collections has been increased to 500. The previous limit of 20 was put in place back in the prototype stage of the service and somehow it survived. We typically recommend 500 as a good number for balancing the needs of consumers while maintaining the performance/load of the server.
- The only reason this might be an issue for consumers is if you were requesting a large collection (e.g. Titles), relying on the server-driven paging size of 20, and you’re now being handed 500 titles at once all of a sudden. If that much data is more than you need (or want) at once, then you can just do client-side paging (via $top and $skip) to control the amount of data you get back per request.
- The Title type has a new property called ShortSynopsis. As you can imagine, this property is a shortened version of the existing Synopsis property. The other useful thing about ShortSynopsis is that it doesn’t include any HTML (unlike Synopsis) in its contents, so if you’re developing a client UI that doesn’t want to parse HTML content (or can’t, as is the case with SL in-browser), ShortSynopsis is your new solution.
- Each delivery format of a Title (Instant, DVD, Blu-Ray) now has its own distinct Rating and Runtime properties (e.g. Dvd/Rating, Instant/Runtime, etc.). This allows each format to differ in their MPAA rating and their overall runtime, which will happen in practice, and so that extra flexibility was needed in the data.
- In order to maintain backwards compatibility, and keep the ease-of-use of the data, we wanted to keep the Rating and Runtime properties directly off a Title. Since a title can have multiple formats, and each of those formats can have different ratings and runtimes, we obviously had to decide on which of the three take preference in representing the “canonical” format. Basically, the Title’s “root” Rating and Runtime values will come from the first format that is available, in the following order: Blu-Ray, DVD, Instant. Therefore, if a Title is available in Blu-Ray, it’s Rating property will always be equal to its BluRay/Rating property (the same goes for the runtime). If a Title isn’t available in Blu-Ray but it is in DVD, the DVD values will be used, and so on. If you don’t like this behavior, you can use the individual specific rating and runtime values.
Those of you that are consuming the service from a dynamic language (e.g. JavaScript, Ruby), you should have nothing to worry about here. But, if you’re consuming the service from a static language (e.g. C#, Java), you will most likely need to regenerate your proxy classes. I say “most likely” because every client differs in how it treats missing properties. The .NET client for instance, by default, will throw an exception if the server returns a property that doesn’t exist on the client-side proxy type. You can get around this by setting the DataServiceContext.IgnoreMissingProperties property to true, or just re-generate the proxy.
If you run into any issues, please feel free to reach out. Also, make sure to let us know if you’re doign anything cool with the service as well.
