Ruby Best Practices

Chapter 2. Designing Beautiful APIs

As developers, we experience the difference between good and bad programmatic interfaces every single day. Some modules we work with seem to speak right to us, clearly expressing their role in our project in a loud, confident voice. Others mumble nonsense and occasionally freak out on us in ways we’d never expect. In many ways, our code is only as good as its application programming interface (API). Good APIs provide exactly what we need, in the way we need it. Bad APIs confuse us and make us jump through hoops to get things working, pushing us one step closer to the dreaded “Big Rewrite.” Ruby provides the tools to build beautifully clear interfaces, but these same tools can produce chaos and disarray when placed in misguided hands.

In this chapter, we’ll take a look at the infrastructure Ruby provides to help you design solid interfaces. We’ll examine both the technical details and the motivation behind the various different approaches, allowing you to see both the how and why that’s involved in designing “Rubyish” APIs. We’ll begin by looking through a practical example of API design from a real project, and then move on to more specific tips and tricks. Along the way, you’ll gain both conceptual and technical understanding of how to design suitable APIs for your Ruby projects.

Designing for Convenience: Ruport’s Table() feature

In Ruby Reports (Ruport), virtually all of our users will need to work with tabular data at some point. This data can ...