OSCON 2014 & REST API Client Best Practices

Hao Nguyen

August 4, 2014

Mark Lavin, Caktus Technical Director and author of the forthcoming LightWeight Django was recently at OSCON 2014 in Portland where he gave a talk on improving the relationship between server and client for REST APIs. OSCON, with over 3000 attendees, is one of the largest open source conferences around. I sat down with him to ask him about his time there.

Welcome back! This was your second year speaking at OSCON. How did you enjoy it this year?

I enjoyed it. There’s a variety of topics at OSCON. It’s cool to see what people do with open source—there’s such a large number of companies, technologies, and approaches to solutions. There were great conversations and presentations. I especially liked Ignite OSCON where people gave really well-prepared 5 minute talks.

I participated in the OSCON 5k [Mark received 5th place] too. There were a lot of people out. We went over bridges and went up and down this spiral bridge twice. That race was pretty late for me but fun [began at 9pm PST, which is 12AM EST].

Why did you choose REST API client best practices as a talk topic?

It was something that came out of working on Django LightWeight. I was writing about building REST APIs and the javascript clients. This prompted a lot of thinking and researching on how to design both ends of it from Julia (Ellman, co-author) and I. I found a lot of mixed content and a lot of things I wasn’t happy to see—people skimping on what I felt were best practices.

I think that you need to think about API design in the same way that you think about websites. How is a client going to navigate the API? If it’s asking for a piece of information, how is it going to find a related piece of information? What actions is it allowed to take? Writing a good server can make a client easier, something I’ve seen in my work at Caktus.

Why do you think this isn’t a more common practice?

The focus is often on building a really fast API, not building an API that’s easy to use necessarily. It’s hard to write the client for most APIs. The information that gets passed to the client isn’t always sufficient. Many APIs don’t spend the time to make themselves discoverable, so the client has to spend a lot of work hard coding to make up for the fact that it doesn’t know the location of resources.

What trade-offs do you think exist?

With relational data models, sometimes you end up trading off normalization. A classical “right way” to build a data model is one that doesn’t repeat itself and that doesn’t store redundant data in a very normalized fashion. Denormalizing data can lead to inconsistencies and duplication, but, at times, it can make things faster.

The API design is similar particularly when you have deeply relational structures. There were a lot of conversations about how do you make this trade off. Interestingly enough, Netflix gave a talk about their API and its evolution. They said they started with a normalized structure and discoverable API and found that eventually they had to restructure some pieces into a less normalized fashion for the performance they needed for some of the settop boxes and game boxes that query their API.

We heard you had an opportunity to give a tutorial. Tell us more about it.

I had the opportunity to help Harry Percival. He recently released a book on Python web development using test-driven development. We’d emailed before and so we knew each other a little bit. He asked me to help him be a TA so I spent Monday morning trying to help people follow his tutorial and get set up learning Python and Django. It was unexpected, but a lot of fun, similar to what Caktus has done with the bootcamps. I like to teach. It’s fun to be a part of that and to help someone understand something they didn’t know before. There were a lot of people interested in learning about Python and Django. I was just happy to participate.