Tim Rogers - Speaking

Miles more maintainable: building APIs with the middleware pattern

When you’re building an API, things start off simple. But before you know it, there’s lots of logic you want to build abstractions around and reuse - for example authentication, input validation and pagination. In the world of Rails, this usually means having a long list of callbacks living in your ApplicationController using ActionController’s before_action magic.

This leads to:

tangled data dependencies: callbacks depend on data retrieved by other callbacks and stored in instance variables - the authenticated user, for example - making your code hard to reason about
hidden behaviour: where all those excepts and onlys on your before_actions are hard to reason about and separated from your code, usually living in ApplicationController!
difficulties with testing: unit testing methods inside a controller is hard!

The middleware pattern can help us to bring sanity to our APIs and make them miles more maintainable.

This talk is based on a blog post I wrote, “When good controllers go bad: getting started with Coach”.

I gave this talk with a focus on Ruby at RubyC in Kiev, Ukraine 🇺🇦 on 2nd June 2018 and at RubyConf Kenya 2018 in Nairobi, Kenya 🇰🇪 on 29th June 2018.

Download the Ruby-focused slides from Kiev and Nairobi

I also gave this talk in a more language-agnostic form at WebCraftConf 2019 in Kingston, Jamaica 🇯🇲 on 15th March 2019.

Download the language-agnostic slides from Kingston

“You never get a second chance to make a first impression”: Writing great "getting started" documentation

As the old saying goes, “you never get a second chance to make a first impression”. When you first meet someone new (not least at a conference for documentarians!), those first few moments set the tone. In exactly the same way, the experience your user has when they first “meet” your product and get to grips with it will set the tone for your entire relationship with them.

This talk looks at how you can make a great first impression with the "getting started" documentation for your API, working alongside your reference docs, seeking not only to teach the user how to use our product, but also to explain the fundamental concepts behind it and to bring the user to the all-important “aha!” moment where they see the value in what we’re offering.

I gave this talk at Write the Docs EU 2017 in Prague, Czech Republic 🇨🇿. I'm planning to do it again soon.

Watch on YouTube