Conference Schedule

Track one or two? Eeenie, meenie, miney, moe…

log in to bookmark.

RESTful APIs: Promises & Lies

A Talk presented by Tareque Hossain


Wednesday, September 7th 11:20 a.m.–noon




Over the last few years RESTful APIs have become an integral part of many django projects. But some of the fundamental questions still remain unanswered. How do you decouple resources from models, formatting from definitions, authorization from authentication? How should you define resources? How do you handle pagination? Deliver facets? Prevent abuse? Implement versioning? Let's have a look.


Implementing RESTful APIs for django applications used to be the talk of the town. Eventually a few API frameworks emerged. Some were designed to provide a quick & easy path to implementation. Some focused on decoupling components as much as possible. At the same time, numerous blog posts were published and emails exchanged seeking/ pitching sound API concepts & best practices. Somehow till this date, there is arguably no single solution that addresses all of the major concepts/practices around designing & securing RESTful APIs. Why? What were the promises? What were the lies?

In this talk, an attempt is made in identifying these concepts/practices in light of recent experiences with a PBS Education Technology project. In designing a RESTful API, it is important to establish a relatively simple resource definition that is uniform across all resources, yet powerful enough to deliver errors, pagination, facets as well as data from attributes/ methods of various models/ instances. It is also desirable to have serialization formats decoupled from these definitions and delivered to consumers according to their preferences.

Securing the API is a complex task as well. Not all RESTful APIs are meant for public consumption. Yet it is necessary to make AJAX calls that might leave the API vulnerable and expose security patterns. This talk highlights why it is important to have decoupled authentication backends, why 2-legged-OAuth can be an excellent choice in protecting the API and how adding pre-approved tokens can help differentiate between user/ application specific calls.

Concepts/ best practices evolve over time. So should the API. Sometimes it is necessary to perform refactoring or optimization that alters the API significantly. In any case, establishing a path to versioning API components is a prudent choice. Here, the fundamentals are explored.

Rest of the talk presents how PBS Education Technology team enhanced django-piston to incorporate the ideas and suggestions mentioned above. Also consumer side practices and security implementations are demonstrated using code examples.