top band

Friday 4:15 p.m.–5 p.m.


Miguel Grinberg

Audience level:
Best Practices & Patterns


Writing a fully complaint REST API is hard, so hard it is too common for APIs to violate one or more of the REST architectural principles. In this talk I will describe the six REST principles, and I will tell you what happens if you don't follow them.


The world is full of badly designed and difficult to use Web APIs. The REST architecture tries to make APIs better by defining a set of guiding principles that give APIs a predictable behavior modeled after the familiar HTTP protocol of World Wide Web fame. Unfortunately some of the REST principles are hard to grasp, so many APIs implement them incorrectly. For example, developers used to build APIs using other paradigms may find the focus on resources and the state transitions unconventional. Also, some of the REST principles go against well established practices for building traditional Web applications, so developers that transition to APIs usually apply techniques they learned before, such as those involving user sessions or cookies, without knowing or understanding why those are frowned upon in APIs. Now don't get me wrong, I have built bad APIs as much as the next person, so in this session I do not plan to point fingers at anyone. My intention is to explain the REST principles as I understand them and in plain English, so that the next time you design an API you have all the elements to decide if this approach is the right one for your project. I will sort the six principles by their level of complexity and then systematically go through them starting from the easier ones. For each one I will tell you what do you gain if you abide by it, and what do you lose if you don't. I will give special attention to the "Uniform Interface" principle, the most complex of the set, which I will cover as four sub-topics. To conclude, I will do a live demonstration, where I will play the part of an API client and show you how to access an example API written in Python with the Flask microframework. Starting with the API documentation as a guide I will show you how to work with this example API using a command line HTTP client.
bottom band background