00:00:15.689
All right! Okay, I think we are ready to get going. Thanks so much to everyone for being here. This is both of our first times at RailsConf, and we're super excited to be here. It’s been a fantastic week. So fantastic that I'm losing my voice and I've caught a little cold. Please forgive me if I have a crackly voice; I'm all hopped up on cold meds, so this should be an entertaining presentation anyway. My name is Rosie, and I'm joining you here from Minneapolis. This lovely lady here is Sonja, all the way from Washington, D.C. Today, Sonja and I are going to talk about APIs, but we're going to take a slightly different approach to this talk. We both have been through fairly major career pivots in the past few years that have led us to be in front of you here today as Rails developers. So we wanted to take all of our past experiences and frame this conversation in a way that we thought might be relevant and interesting.
00:02:01.630
My background before I made the transition to Rails development was in architecture—bricks and steel architecture, not software architecture—and city planning. Sonja also worked as a writer and graphic designer in a former life. We've both spent a lot of time thinking about the building process and design elements. To start this presentation, I'm going to talk a little bit about the importance of patterns in both the built environment and in software that support good design. Then I'll get into the need for this talk and describe why we think you should consider building the API first. Sonja will go over some best practices, and I'll bring it home with a bit of conversation about some tools and best practices that you can use to build your API.
00:02:48.260
As I mentioned, my background before I got the wild hair to become a Rails developer was in architecture and planning. Along the way, learning to program and learning Rails has been a fascinating journey, partially because everywhere I look, I find parallels between the built environment and the Rails software stack. One of these parallels is the role that patterns play in both worlds. Before we dive into the meat of this talk, I want to share a quick story about how I came to this topic and why we thought it might be relevant to approach it from the perspective of design patterns. One of the most influential books in the last half-century in architecture is a book by Christopher Alexander called 'A Pattern Language.' If you're unfamiliar, a pattern language, in a nutshell, is a method of describing good design practices. It should facilitate successfully solving very large complex design problems. These patterns are tools to help abstract away some of the complexity in our worlds so that our little brains can wrap around how to approach solutions.
00:04:54.870
Design patterns in the built environment go back hundreds and hundreds of years and are rooted in how we as humans experience our surroundings and relate to each other. For me, as an architecture student, understanding patterns was a big part of my training. I’m sure you all guessed where this is going. This book came out in 1977 in response to a few decades of really bad architecture that went against good design patterns developed over the ages. They ignored these patterns that support the tried-and-true ways humans want to inhabit cities and essentially created many buildings that were really awful spaces for humans. Now we fast-forward 20 years, and these ideas reemerge in the software world. Martin Fowler, for example, writes about patterns; all of the language he uses to talk about object-oriented software design comes straight out of the architecture world. On this book's Wikipedia page, it points directly to Christopher Alexander's book as an inspiration for Fowler’s work in software. Most people probably take it for granted at this point, but all of the language we use to talk about software was lifted straight out of the architecture world.
00:06:36.500
As an extension, I think the way the profession thinks about the organization of things; we like to think that what we're doing is new. But if you take a couple of steps back, the concepts are really the same. I don’t know if Fowler and Alexander knew each other, but I think they would have gotten along. One of the things I like to imagine is them going out on Tuesdays to drink cappuccinos and have these really intense philosophical conversations about the order of things. Even though at a glance it seems they come from very different worlds, at a conceptual level, I think they would be having the same conversation. Coming back to Rails, when I started to think about software, I never really brought this lens of patterns with me, which meant I was primed to drink the Rails Kool-Aid: convention over configuration. Obviously, this was just really smart design. These conventions mapped very cleanly in my brain to patterns, and I just got it right away.
00:08:28.640
At first, the process of learning Rails was a smooth progression of these elegantly designed pieces sort of clicking into place. Then inevitably, I stumbled into area after area where Rails does not provide conventions or strong opinions on what to do. I would look to my right, look to my left, talk to the developers around me, and realized everybody had a different opinion, and honestly, this is when learning Rails got kind of hard. This brings us to today. One of these areas that we found without a clear sort of mainstream convention that everyone seems to agree on was APIs. Beyond using Jbuilder and the basic happy path of a Rails application, there wasn't clear guidance on how to deal with APIs, and honestly, this really surprised me. Most of the hard problems I deal with today are related to data transfer at my current job. Building applications that manage large amounts of data is a really important piece of our applications.
00:10:38.490
So, thinking about this more as developers—as a new developer, I should say—when I have a question, I, of course, ask the internet. This sent me down a rabbit hole where everyone was suggesting something slightly different, and nobody seemed quite satisfied with how they were dealing with this problem. I read about lots of solutions, all having varying degrees of success. They were all interesting and somewhat helpful, but they weren't the solid answer I was looking for, and it was really frustrating. I knew this wasn't rocket surgery. It left me feeling like, 'Okay, Rails, if you're so opinionated, why don’t you have an opinion on this? What should I do?' Here we are, and we believe building APIs is one of the critical areas where we should have a shared solution because this is how our applications talk to each other. This is where my application and your applications cease to be my problem and your problem; they're everyone's problem, especially if we have a public API.
00:12:09.370
To bring this back to architecture, the evolution of our great cities is really the evolution of shared problems becoming shared solutions in elegant and innovative ways. We tend to think of the development of cities in terms of buildings, but buildings come and go. In reality, the interesting story—with my architecture hat off and my city planner hat on—is really the story of infrastructure; how we came together and agreed on how electricity should be delivered, how our sanitation systems should be constructed, and how we wanted to get from point A to point B. So, the starting point of this talk is that APIs should act as the infrastructure for our applications. If passing around data is the most important thing your app does, then your APIs should be elevated from something we cobble together to something we have a solid solution for.
00:14:15.620
Starting with the API and building your client applications around it opens up all sorts of interesting possibilities. Carrying it out to the full realization of this concept, your APIs could be the foundation that supports a variety of clients such as mobile applications or rich JavaScript framework clients. By decoupling your REST API from your client, you can more easily support multiple clients and have a system that is much more flexible but also organized. If a mobile interface is really important to your application, your REST API can support multiple native mobile apps with minimal duplication across platforms. That's a good thing. You can also use the same API to serve data to a JavaScript framework, again with very little duplication. Your API should be the common denominator; without a good standardized server solution, you can't have a standardized way for different clients to communicate with the servers.
00:16:08.500
We’ve discussed some reasons why this new generation of Rails applications must embrace a variety of clients; the API should be the foundation and where we think you should consider starting. One, your application will be designed to pass around data from the get-go. Two, if you need to support multiple clients, you can easily do this with minimal duplication across platforms. Three, if you create the standardized server code first, you'll easily support the creation of standardized client code. Now I'm going to pass it off to Sonja.
00:18:12.780
So let's discuss some of the API best practices. There are a few that are very important to begin with when you're constructing your API. But before we jump into them, I think it's important to consider this question: Why is a well-designed API so important? In this image, we see Fallingwater, a cantilever home in Pennsylvania built in 1935, that is among one of the greatest assets to the architectural legacy of Frank Lloyd Wright. It is built partly over a waterfall, driving its name from its situation, and has been conserved as a museum since 1963. In other words, this is a huge asset to the legacy of Frank Lloyd Wright. A well-designed API can be that of a company's greatest assets.
00:19:44.080
Why? Because users invest their time and not-so-obvious ways. In the obvious ways, they are writing to it, buying products that use it. They tell their friends and communities about how great this API is. They start writing blog posts about it; they're creating hype. Basically, the less obvious ways is that users are digging into it and spending a significant amount of time learning how it works and playing around with the code. A poorly designed API can be a huge liability. The same users who would have been promoting it and using it as inspiration for new products are now calling in for support and asking you what to do about the problems that you've created with the API, and taking away from your productivity. Or, worst-case scenario, they’re just taking one look at your API and then running away from it.
00:21:45.350
So, the first guideline when following best practices is to design your APIs for experience and readability, not for data alone. In other words, an API should reflect how something is used, not just how it is stored. In fact, I hate to say it, but nobody really cares what your database looks like. People want to know how it operates and how they can use it. The experience should not fill your fellow developer with misery or regret; it should be methodical and can lead them to discover what they need.
00:22:55.990
This leads me to the next best practice: consistency. By providing a single API that can serve multiple clients, you get consistent client solutions across platforms. This includes having single endpoints and clean routes throughout your API. It's kind of like a telephone pole with all the cables and wires running through and around it. The pole is built with specific plug-ins for specific wires and purposes, allowing electricity to flow from the power plant to your computer screen or your light bulb. Similarly, an API call retrieves a particular data set from your database and expects a consistent return every time. Without this, we get something hideous and terrifying. Unfortunately, this slum infrastructure does not support consistency or a sustained development of regulated wiring—it's inefficiency at its finest. You should never have your API making someone feel like they’re in that situation.
00:23:55.530
Coming from the writing and editing world, documentation is profoundly important, especially having learned how to code later in life. I love a well-documented gem or anything I'm trying to use. I love when I see a lot of documentation written the right way. Documentation is very important to the widespread use of your API, public or not; it should act as a bonus layer of information—a glimpse into a developer's mind that assumes nothing and notes everything. It should sit on top of an already easy-to-understand API. In other words, don’t make the documentation do the dirty work; your API should already be understandable, and you're just providing this layer of documentation on top of it.
00:25:42.480
For those of you who are just grumbling at my last slide, let's talk about a service that makes documentation a cinch—one that we found is APIary. It's a structured interactive tool that follows the necessities of documentation using Markdown and a template for easy use. The result is an intuitive document incorporating the basic necessities that all documentation should contain. Generally speaking, API documentation should include the following: examples of the full request and expected response; a list of error codes and their significance; a searchable HTML interface; and communication of versioning and deprecation schedules so you don't catch anyone off guard who happens to be using an API version you’re planning to move forward from.
00:27:22.400
The lifespan of an API is important to consider. It can be difficult to choose how you're going to version or what your strategy will be, but you should approach it as if you have to get the first version of your API absolutely right. It makes it easier down the road. The most important thing to remember is that versioning is inevitable, and plan for deprecation from version 1. I also like to think of APIs as if they were rescue dogs. If anyone knows me from the Flatiron School, I'm obsessed with rescue animals. So I had to tie this back in for a moment. This is not a Westminster Kennel Club winning dog, but more like a little rescue pup. He has limitless potential to be an incredible pet if you just give him a chance.
00:29:24.650
Just like you want to set your rescue pup up for success, you’ll want to do the same for your API. For starters, neither this dog nor your API require any fancy things; they simply crave repetition and unconditional support in order to be successful. Give them what they need to evolve into their new versions, but don't forget where they came from—the JSON API is one standard for building APIs that is supported by the Rails community. Steve Klabnik’s quote, 'By following shared conventions, you can increase productivity, take advantage of generalized tooling, and focus on what matters in your application.' We like the JSON API standards, so I put an example of it here.
00:31:33.800
Like so many of the tools we've discussed already today, there are more out there, and there are a lot of great ones being developed right now. Building APIs is a shared problem for most developers. It seems there is now a general shared understanding of what a good API should consist of. A shared solution is the next step so we can turn these best practices into conventions. For the last couple of months, we've been asking every developer we encounter what they use to build APIs. The answers were usually Rails or Sinatra, combined with some of its tools available on Ruby Toolbox, and usually a partially hand-rolled solution.
00:33:12.220
We also heard how Rails is increasingly being used to create a REST API that talks to a mobile client, and there seems to be growing interest in using Rails for JavaScript frameworks. These may not be traditional Rails applications, but people still recognize the value of Rails for creating a REST API. After talking to lots of people, it was evident that an agreed-upon solution still wasn’t clear, and the whole thing just required way too much thinking. There are so many ways to cobble something together, but we wanted to know: what's the Rails way? What will be the Rails way to build a solid API? Again, we wonder: if Rails is so opinionated and committed to this idea of conventions, tell us what to do! We no longer have to be pioneers venturing out into the unknown.
00:35:18.360
In the middle of all these conversations, we did see a Rails way emerging. It's not baked in yet, but lo and behold, there are solutions emerging from the core Rails team that provide an opinion on how to create REST APIs. We’ve been exploring Rails API in combination with Active Model Serializers for building an API where you only need the JSON endpoints. Rails API utilizes most of the same generators and conventions and looks very familiar for this new generation of applications where the API is your infrastructure that supports a family of client applications. We think this is what the future might look like.
00:37:35.790
The Rails API is really just a miniature Rails stack where they've skipped all the stuff you need if you're creating views, producing a solution that is lighter and faster than the full Rails app. But it does still come with a full suite of built-in solutions for many poorly understood problems, and the documentation includes a laundry list of things that are handled in the Middleware layer and the Action Pack layer. This is definitely a win! For example, you might understand perfectly how to hand-roll a solution for IP spoofing attacks, but even if you do, why spend time doing this when Rails is going to do it for you? Thanks, Rails.
00:39:52.490
And again, if there's a solution for something already out there, I’d rather use that than reinvent the wheel. The other tool we're exploring is Active Model Serializers. Short serializers replace hash-driven development with object-oriented development; for example, with Active Model Serializers, when you're using 'render json' in your controllers, Rails will search for a serializer for the object and use it if available. It's an elegant solution for creating server-side APIs that don't require a view layer. They act a lot like models and can be easily customized. Active Model Serializers also follows the JSON API standard, so you know you're creating a standardized API that will easily communicate with a variety of clients. It really helps take the guessing out of how your JSON API should be structured.
00:41:45.045
Okay, so it's time to start wrapping things up. Here are a few points to leave everyone with: We find it's increasingly important to design APIs following patterns and conventions that fit into the system as a whole. To do this, we can leverage existing best practices and tools, and by doing so, we will create APIs that support a more organized structure for applications. I was inspired by Yehuda Katz's keynote yesterday, and I think it's time for us as a community to move API design out of the area of expertise and into the area of our collective shared solution. We will all benefit!
00:43:11.940
Trivial choices are the enemy. Drink your convention-over-configuration Kool-Aid, but brush your teeth afterwards because Kool-Aid is not good for you! Anyway, we're often trying to solve the same problem. When this is the case, we should agree on a strong convention and follow it; we will all benefit in the end. And don't forget about who or what else is going to want to use this API in the future and plan accordingly. This may include native mobile applications or a JavaScript client-side framework, or something else we haven’t even imagined yet. By designing our APIs today to be consistent across platforms, we can make changes to our client-side applications in the future much easier.
00:45:20.680
So tomorrow, someone's not trying to use your hand-rolled API that didn’t really follow any established design patterns or conventions, and you have to explain that, 'Well, it seemed like a good idea at the time.' For those of you who aren't from Minneapolis, this is the ugliest building in the Minneapolis guidelines. We all drive by and shake our heads, but worse, your application gets scrapped because it was poorly organized from the get-go and too rigid to update. Oh, and last but not least, document all the things! Documentation is the key to your API being used successfully.
00:47:14.250
We've come to the end, and I hope to leave you with one thought: I hope when you approach your next project, you'll consider building your API first. All right, thanks everybody!