0:00:17.420,0:00:20.030
ROSIE HOYEM: All right. OK. I think we are[br]ready

0:00:20.030,0:00:22.060
to get going. Thanks so much to everyone

0:00:22.060,0:00:24.770
for being here. This is both of our first

0:00:24.770,0:00:26.990
times at RailsConf and we're super excited[br]to be

0:00:26.990,0:00:30.300
here as well. It's been a fantastic week.

0:00:30.300,0:00:32.150
So fantastic that I'm losing my voice and

0:00:32.150,0:00:33.870
I've gotten a little cold, so please forgive[br]if

0:00:33.870,0:00:36.910
I have a crackly voice. I'm all hopped up[br]on

0:00:36.910,0:00:39.090
cold meds, so this should be an entertaining

0:00:39.090,0:00:41.100
presentation, anyway.

0:00:41.100,0:00:43.059
So my name is Rosie. And I am joining

0:00:43.059,0:00:45.600
you here from Minneapolis, and this lovely[br]lady here

0:00:45.600,0:00:50.000
is Sonja, all the way from Washington D.C.[br]And

0:00:50.000,0:00:52.100
today, Sonja and I are going to talk about

0:00:52.100,0:00:54.850
APIs. But we're going to take a slightly different

0:00:54.850,0:00:58.420
approach to this talk. We both have been through

0:00:58.420,0:01:01.110
fairly major career pivots, in the past few[br]years,

0:01:01.110,0:01:02.370
that have lead us to be in front of

0:01:02.370,0:01:05.900
you here today as Rails developers. So we[br]wanted

0:01:05.900,0:01:07.750
to take all of our past experiences and use

0:01:07.750,0:01:09.990
this to kind of frame this conversation in[br]a

0:01:09.990,0:01:12.880
way that we thought might be relevant and[br]interesting.

0:01:12.880,0:01:15.350
So, my background before I made the transition[br]to

0:01:15.350,0:01:19.070
Rails development was in architecture, as[br]in bricks and

0:01:19.070,0:01:24.130
seal architecture. Not software architecture.[br]And city planning. Sonja

0:01:24.130,0:01:27.229
also worked as a writer and graphic designer[br]in

0:01:27.229,0:01:29.939
a former life. We both spent a lot of

0:01:29.939,0:01:34.780
time thinking about the building process and[br]design elements.

0:01:34.780,0:01:37.729
So to start off this presentation, I'm gonna[br]talk

0:01:37.729,0:01:40.729
a little bit about the importance of patterns[br]in

0:01:40.729,0:01:44.229
both the build environment and software that[br]support good

0:01:44.229,0:01:47.090
design. Then I'll get into the meat of the

0:01:47.090,0:01:49.869
talk and describe why we think you should[br]consider

0:01:49.869,0:01:53.829
building the API first. And Sonja will go[br]over

0:01:53.829,0:01:56.820
some best practices, and I'll bring it home[br]with

0:01:56.820,0:02:00.439
a bit of conversation about some tools and[br]best

0:02:00.439,0:02:04.460
practices that you can use to build your API.

0:02:04.460,0:02:11.180
So, as I mentioned, my background, before[br]I got

0:02:11.180,0:02:13.600
the wild hair to become a Rails developer,[br]was

0:02:13.600,0:02:16.950
in architecture and planning. Along the way,[br]learning to

0:02:16.950,0:02:20.120
program, and learning Rails, has been a fascinating[br]journey,

0:02:20.120,0:02:23.540
partially because everywhere I look, I find[br]these parallels

0:02:23.540,0:02:27.069
between the build environment and the Rails[br]software stack.

0:02:27.069,0:02:30.250
One of these parallels is the role that patterns

0:02:30.250,0:02:32.890
play in both of these worlds. Before we dive

0:02:32.890,0:02:34.239
into the meat of this talk, I want to

0:02:34.239,0:02:37.470
tell a quick story about how I came around

0:02:37.470,0:02:39.730
to this topic and why we thought it might

0:02:39.730,0:02:42.230
be relevant to approach this topic from the[br]perspective

0:02:42.230,0:02:44.900
of design patterns.

0:02:44.900,0:02:46.680
One of the most influential books in the last

0:02:46.680,0:02:49.510
half a century in architecture is this book[br]by

0:02:49.510,0:02:54.310
Christopher Alexander, A Pattern Language.[br]If you're unfamiliar, a

0:02:54.310,0:02:56.959
pattern language, in a nutshell, is a method[br]of

0:02:56.959,0:03:01.650
describing good design practices. A pattern[br]language should facilitate

0:03:01.650,0:03:07.470
successfully solving very large, complex design[br]problems. These patterns

0:03:07.470,0:03:10.230
are tools to help abstract away some of the

0:03:10.230,0:03:12.879
complexity in our world so our little brains[br]can

0:03:12.879,0:03:16.659
wrap around how to approach solutions.

0:03:16.659,0:03:19.480
Design patterns in the build environment go[br]back hundreds

0:03:19.480,0:03:21.549
and hundreds of years, and are very much so

0:03:21.549,0:03:24.319
rooted in how we, as humans, experience our[br]surroundings

0:03:24.319,0:03:27.280
and relate to each other. And, for me, as

0:03:27.280,0:03:30.220
an architecture student, understanding patterns[br]was a big part

0:03:30.220,0:03:31.870
of my training.

0:03:31.870,0:03:35.420
I'm sure you all guess where this is going.

0:03:35.420,0:03:38.579
So this book came out in 1977, and responds

0:03:38.579,0:03:41.959
to a few decades of really, really bad architecture

0:03:41.959,0:03:45.530
that just went in the face of good design

0:03:45.530,0:03:48.579
patterns that had developed over the ages.[br]They ignored

0:03:48.579,0:03:51.610
these patterns that support a tried and true[br]way

0:03:51.610,0:03:55.099
humans want to inhabit cities and essentially[br]ended up

0:03:55.099,0:03:57.400
creating a lot of buildings that were really[br]awful

0:03:57.400,0:03:58.980
spaces for humans.

0:03:58.980,0:04:03.510
And so now, we fast-forward twenty years,[br]and these

0:04:03.510,0:04:06.900
ideas re-emerge in the software world, and,[br]Martin Fowler,

0:04:06.900,0:04:10.719
for example, is writing about patterns. Not[br]only is

0:04:10.719,0:04:13.170
he writing about patterns, all of the language[br]that

0:04:13.170,0:04:16.399
he uses to talk about object-oriented software[br]design, comes

0:04:16.399,0:04:19.440
straight out of the architecture world.

0:04:19.440,0:04:21.720
On this book's Wikipedia page, they point[br]directly to

0:04:21.720,0:04:25.380
Christopher Alexander's book as an inspiration[br]for Fowler's work

0:04:25.380,0:04:28.530
in software. Most people probably take it[br]for granted

0:04:28.530,0:04:30.660
at this point, but all of the language that

0:04:30.660,0:04:33.440
we use to talk about software was lifted straight

0:04:33.440,0:04:36.950
out of the architecture world. And, as an[br]extension,

0:04:36.950,0:04:39.220
I think the way the profession thinks about[br]the

0:04:39.220,0:04:42.510
organization of things. We like to think that[br]what

0:04:42.510,0:04:45.510
we're doing is new. But take a couple steps

0:04:45.510,0:04:49.790
back, and the concepts are really the same.

0:04:49.790,0:04:52.670
I don't know if Fowler and Alexander knew[br]each

0:04:52.670,0:04:53.710
other. But I think they would have gotten[br]along.

0:04:53.710,0:04:55.480
And one of the things I like to imagine

0:04:55.480,0:04:58.940
is them going out on Tuesdays to drink cappuccinos

0:04:58.940,0:05:02.330
and have these really intense philosophical[br]conversations about the

0:05:02.330,0:05:06.740
order of things. Even though, at a glance,[br]it

0:05:06.740,0:05:08.230
seems they come from very different worlds,[br]at a

0:05:08.230,0:05:10.050
conceptual level, I think they would be having[br]the

0:05:10.050,0:05:12.760
same conversation.

0:05:12.760,0:05:16.450
So, coming back to Rails, when I started to

0:05:16.450,0:05:19.000
think about software, I inevitably brought[br]this lens of

0:05:19.000,0:05:22.600
patterns with me, which meant I was super[br]primed

0:05:22.600,0:05:27.080
to drink the Rails Kool-Aid. Convention over[br]configuration? Obviously

0:05:27.080,0:05:31.010
this was just really smart design. These conventions[br]mapped

0:05:31.010,0:05:33.820
very cleanly in my brain to patterns, and[br]I

0:05:33.820,0:05:36.850
just got it right away.

0:05:36.850,0:05:38.950
At first, the process of learning Rails was[br]just

0:05:38.950,0:05:42.670
a smooth progression of these elegantly designed[br]pieces sort

0:05:42.670,0:05:47.670
of clicking into place. Then, inevitably,[br]I stumbled into

0:05:47.670,0:05:51.350
area after area where Rails does not provide[br]conventions

0:05:51.350,0:05:54.190
or strong opinions on what to do. And I

0:05:54.190,0:05:55.980
would look to my right, look to my left,

0:05:55.980,0:05:59.590
talk to developers around me, and realized[br]everybody had

0:05:59.590,0:06:01.810
a different opinion. And honestly this is[br]when learning

0:06:01.810,0:06:04.880
Rails got kind of hard.

0:06:04.880,0:06:07.990
And so this brings us here, today. One of

0:06:07.990,0:06:10.580
these areas that I, that we've found without[br]a

0:06:10.580,0:06:13.470
clear, sort of mainstream convention that[br]everyone seems to

0:06:13.470,0:06:17.000
agree on was APIs. Beyond using JBuilder and[br]the

0:06:17.000,0:06:21.080
basic happy path Rails application, there[br]wasn't clear guidance

0:06:21.080,0:06:24.340
how to deal with APIs. And honestly this really

0:06:24.340,0:06:26.710
surprised me.

0:06:26.710,0:06:29.660
Seems to me, and maybe many of you, most

0:06:29.660,0:06:31.550
of the hard problems I deal with today are

0:06:31.550,0:06:35.440
related to data transfer. At my current job,[br]this

0:06:35.440,0:06:37.530
is what we do. We build applications that[br]manage

0:06:37.530,0:06:40.000
large amounts of data. This is a really important

0:06:40.000,0:06:44.680
piece of our applications. And so, thinking[br]about this

0:06:44.680,0:06:47.520
more as developers, as a new developer I should

0:06:47.520,0:06:50.190
say. When we have a question, I, of course,

0:06:50.190,0:06:53.080
ask the internet. This sent me down a rabbit

0:06:53.080,0:06:56.470
hole where everyone was suggesting something[br]slightly different, and

0:06:56.470,0:06:58.740
nobody seemed quite satisfied with how they[br]were dealing

0:06:58.740,0:06:59.700
with this problem.

0:06:59.700,0:07:02.330
I read about lots of solutions, all having[br]varying

0:07:02.330,0:07:06.440
degrees of success. It was all interesting.[br]And somewhat

0:07:06.440,0:07:08.240
helpful. But it wasn't the solid answer I[br]was

0:07:08.240,0:07:12.810
looking for. And honestly it was really frustrating.[br]I

0:07:12.810,0:07:15.290
knew this wasn't rocket surgery, and it left[br]me

0:07:15.290,0:07:19.280
feeling like, OK Rails, if you're so opinionated,[br]why

0:07:19.280,0:07:21.900
don't you have an opinion on this? What should

0:07:21.900,0:07:23.860
I do?

0:07:23.860,0:07:28.720
And so, here we are. And we believe building

0:07:28.720,0:07:31.650
APIs is one of the critical areas where we

0:07:31.650,0:07:36.210
should have a shared solution because, obviously,[br]this is

0:07:36.210,0:07:39.080
how our applications talk to each other. This[br]is

0:07:39.080,0:07:42.990
where my application and your applications[br]cease to be

0:07:42.990,0:07:46.180
my problem and your problems, and they're[br]now everybody's

0:07:46.180,0:07:50.210
problem. Especially if we have a public API.

0:07:50.210,0:07:54.860
So, for one moment, bring this back to architecture.

0:07:54.860,0:07:57.480
The evolution of our great cities is really[br]the

0:07:57.480,0:08:01.950
evolution of shared problems becoming shared[br]solutions in elegant

0:08:01.950,0:08:04.470
and innovative ways. We tend to think of the

0:08:04.470,0:08:07.290
development of cities in terms of buildings,[br]but buildings

0:08:07.290,0:08:10.320
come and go, in reality. The interesting story,[br]and

0:08:10.320,0:08:11.840
here I take off the architecture hat and put

0:08:11.840,0:08:14.240
on the city planner hat, is, is really the

0:08:14.240,0:08:17.750
story of infrastructure. How we came together[br]and agreed

0:08:17.750,0:08:21.720
how electricity should be delivered. How are[br]sanitation systems

0:08:21.720,0:08:24.170
should be constructed. And how we wanted to[br]get

0:08:24.170,0:08:28.630
from point A to point B.

0:08:28.630,0:08:30.690
So the starting point of this talk is that

0:08:30.690,0:08:35.640
APIs should act as the infrastructure for[br]our applications.

0:08:35.640,0:08:38.089
If passing around data is the most important[br]thing

0:08:38.089,0:08:40.399
your app does, then your APIs should be elevated

0:08:40.399,0:08:43.458
from something hobble together to something[br]that we have

0:08:43.458,0:08:47.290
a solid solution for. And starting with the[br]API

0:08:47.290,0:08:50.529
and building your client applications around[br]it opens up

0:08:50.529,0:08:53.750
all sorts of interesting possibilities.

0:08:53.750,0:08:56.279
Carried out to the full realization of this[br]concept,

0:08:56.279,0:08:59.189
your APIs could be the foundation that supports[br]a

0:08:59.189,0:09:03.540
variety of clients, such as mobile applications[br]or rich

0:09:03.540,0:09:07.910
JavaScript framework clients. By decoupling[br]your REST API from

0:09:07.910,0:09:11.750
your client, you can more easily support multiple[br]clients

0:09:11.750,0:09:14.339
and have a system that is much more flexible,

0:09:14.339,0:09:16.089
but also organized.

0:09:16.089,0:09:21.740
If a mobile interface is really important[br]to your

0:09:21.740,0:09:24.740
application, your REST API can support multiple[br]native mobile

0:09:24.740,0:09:27.860
apps with minimal duplication across platforms.[br]This is a

0:09:27.860,0:09:30.490
good thing. You can also use the same API

0:09:30.490,0:09:33.709
to serve data to a JavaScript framework. Again,[br]with

0:09:33.709,0:09:36.720
very little duplication.

0:09:36.720,0:09:40.420
Your API should be the common denominator.[br]Without a

0:09:40.420,0:09:43.399
good standardize server solution, you can't[br]have a standardized

0:09:43.399,0:09:46.579
way for different clients to talk to the servers.

0:09:46.579,0:09:50.050
All right. So we've discussed some reasons[br]why, for

0:09:50.050,0:09:53.370
this new generation of Rails applications[br]that must embrace

0:09:53.370,0:09:55.939
a variety of clients, the API should be the

0:09:55.939,0:10:00.649
foundation, and where we think you should[br]consider starting.

0:10:00.649,0:10:05.389
So, one, your application will be designed[br]to pass

0:10:05.389,0:10:09.069
around data from the get-go. And reason two,[br]if

0:10:09.069,0:10:11.180
you need to support multiple clients, you[br]can easily

0:10:11.180,0:10:15.629
do this with minimal duplication across platforms.[br]And three,

0:10:15.629,0:10:18.860
if you create the standardized server code[br]first, you'll

0:10:18.860,0:10:21.920
easily support the creation of standardized[br]client code.

0:10:21.920,0:10:27.449
OK. Now I'm gonna pass it off to Sonja.

0:10:27.449,0:10:31.779
SONJA HALL: All right. So, let's discuss some[br]of

0:10:31.779,0:10:34.910
the API best practices. There are a few that

0:10:34.910,0:10:37.730
are very important to begin with, when you're[br]constructing

0:10:37.730,0:10:40.410
your API. But before we jump into them, I

0:10:40.410,0:10:43.709
think it's important to consider this question.[br]Why is

0:10:43.709,0:10:46.939
a well-designed API so important?

0:10:46.939,0:10:52.569
Well, in this image we see falling water,[br]going

0:10:52.569,0:10:54.560
back to architecture just for a moment. This[br]is

0:10:54.560,0:10:57.649
a catilever home in Pennsylvania, built in[br]1935, that

0:10:57.649,0:10:59.879
is among one of the greatest assets to the

0:10:59.879,0:11:02.519
architect and design thinker Frank Lloyd Wright.

0:11:02.519,0:11:05.110
It is built partly over a waterfall, deriving[br]its

0:11:05.110,0:11:08.649
name from its situation. And will, and has[br]been

0:11:08.649,0:11:11.379
conserved as a museum now since 1963. So,[br]in

0:11:11.379,0:11:14.620
other words, this is a huge asset to the

0:11:14.620,0:11:18.850
legacy of Frank Lloyd Wright. A well-designed[br]API can

0:11:18.850,0:11:22.910
be that of a company's greatest assets.

0:11:22.910,0:11:27.259
Why? Because users invest their time in obvious[br]and

0:11:27.259,0:11:31.629
not-so-obvious ways. In the obvious ways,[br]you're writing to

0:11:31.629,0:11:34.600
it, buying products that use it. You tell[br]your

0:11:34.600,0:11:37.060
friends and communities about how great this[br]API is.

0:11:37.060,0:11:39.160
You start writing blog posts about it. You're[br]creating

0:11:39.160,0:11:42.300
hype, basically. The less obvious ways is[br]that the

0:11:42.300,0:11:44.720
users are digging into it and spending a significant

0:11:44.720,0:11:47.389
amount of time learning how it works and playing

0:11:47.389,0:11:50.160
around in the code.

0:11:50.160,0:11:53.319
A poorly designed API can be a huge liability.

0:11:53.319,0:11:55.279
The same users who would have been promoting[br]it

0:11:55.279,0:11:57.290
and using it as inspiration for new products[br]are

0:11:57.290,0:11:59.910
now calling it, calling in for support and[br]asking

0:11:59.910,0:12:02.509
you what to do about the problems that you've

0:12:02.509,0:12:05.490
created with the API, and taking away from[br]your

0:12:05.490,0:12:08.269
productivity, or worse case scenario, they're[br]just taking one

0:12:08.269,0:12:10.959
look at your API and then running away from

0:12:10.959,0:12:11.300
it.

0:12:11.300,0:12:14.249
So the first guideline to follow, of the best

0:12:14.249,0:12:17.379
practices, is to design your APIs for experience[br]rather

0:12:17.379,0:12:20.730
than, and readability, not for data alone.[br]In other

0:12:20.730,0:12:24.420
words, an API should reflect how something[br]is used,

0:12:24.420,0:12:26.569
not just how it is stored. In fact, I

0:12:26.569,0:12:28.680
hate to say it, but nobody really cares what

0:12:28.680,0:12:31.059
your database looks like.

0:12:31.059,0:12:33.129
People want to know how it operates, how they

0:12:33.129,0:12:35.180
can use it. The experience should not fill[br]your

0:12:35.180,0:12:38.499
fellow developer with misery or regret, it[br]should be

0:12:38.499,0:12:42.139
methodical and consistent. Which leads me[br]to the next

0:12:42.139,0:12:45.040
best practice of consistency.

0:12:45.040,0:12:47.389
By providing a single API that can serve multiple

0:12:47.389,0:12:52.490
clients, you get consistent client solutions[br]across platforms. This

0:12:52.490,0:12:54.889
includes having single end points and clean[br]routes throughout

0:12:54.889,0:12:57.600
your API. It's kind of like a telephone pole

0:12:57.600,0:13:00.339
with all the cables and wires running through[br]and

0:13:00.339,0:13:03.899
around it. The pole is built with specific[br]plugins

0:13:03.899,0:13:07.870
for specific wires and purposes, allowing[br]electricity to flow

0:13:07.870,0:13:10.139
from the power plant to your computer screen,[br]or

0:13:10.139,0:13:12.660
your light bulb or what have you. And similarly,

0:13:12.660,0:13:16.079
an API call retrieves a particular dataset[br]from your

0:13:16.079,0:13:20.050
database, and expects a consistent return[br]every time.

0:13:20.050,0:13:25.240
Without this, we get this. The alternative.[br]Something hideous

0:13:25.240,0:13:31.029
and terrifying. Unfortunately, this slum's[br]infrastructure does not support

0:13:31.029,0:13:35.139
consistency or sustained development of regulated[br]wiring. It is

0:13:35.139,0:13:38.180
inefficiency at its finest, where everyone[br]seems to have

0:13:38.180,0:13:40.999
adopted a 'to each their own' mentality.

0:13:40.999,0:13:44.240
You should never have your API making someone[br]feel

0:13:44.240,0:13:47.899
like this. So avoid that. Coming from the[br]writing

0:13:47.899,0:13:51.959
and editing world, documentation is so important.[br]Especially having

0:13:51.959,0:13:55.470
learned how to code later in life. I love

0:13:55.470,0:13:59.839
a well-documented gem or, you know, anything[br]I'm trying

0:13:59.839,0:14:01.269
to use, I love when I say a lot

0:14:01.269,0:14:04.660
of documentation, and written the write way.

0:14:04.660,0:14:07.800
So, documentation is very important to the[br]wide-spread use

0:14:07.800,0:14:11.610
of your API. Public or not. It should act

0:14:11.610,0:14:13.839
as a bonus layer of information, though. Like[br]a

0:14:13.839,0:14:17.350
glimpse into a developer's mind that assumes[br]nothing and

0:14:17.350,0:14:19.769
notes everything. It should sit on top of[br]an

0:14:19.769,0:14:23.689
already easy-to-understand API, and so, in[br]other words, don't

0:14:23.689,0:14:26.759
make the documentation do the dirty work.[br]Your API

0:14:26.759,0:14:29.170
should already be understandable, and you're[br]just providing this

0:14:29.170,0:14:33.410
layer of documentation on top of it.

0:14:33.410,0:14:34.910
So if you're the type who just grumbled at

0:14:34.910,0:14:37.579
my last slide, I know you're out there, let's

0:14:37.579,0:14:40.339
chat about a service that makes documentation[br]a sync.

0:14:40.339,0:14:44.490
One that we found was Apiary. It's a structured,

0:14:44.490,0:14:48.519
interactive tool that follows the necessities[br]documentation, using mark

0:14:48.519,0:14:51.470
down and a template for easy usage. The result

0:14:51.470,0:14:55.629
is an intuitive document incorporating the[br]basic necessities that

0:14:55.629,0:14:58.170
all documentation could contain. Should contain.

0:14:58.170,0:15:01.610
So here's an example of Apiary and what it

0:15:01.610,0:15:04.149
might look like when you're doing it. But,[br]generally

0:15:04.149,0:15:07.920
speaking, Apiary or not, all documentation[br]should include the

0:15:07.920,0:15:09.199
following:

0:15:09.199,0:15:12.369
Examples of the full request and expected[br]response, a

0:15:12.369,0:15:15.680
list of error codes, their significance - like,[br]what

0:15:15.680,0:15:21.869
is causing them. A searchable html interface,[br]and communication

0:15:21.869,0:15:24.509
of versioning and deprecation schedules so[br]you don't catch

0:15:24.509,0:15:26.949
anyone off guard who happens to be using an

0:15:26.949,0:15:29.470
API, a version of your API that you're going

0:15:29.470,0:15:32.199
to be moving forward from.

0:15:32.199,0:15:35.009
So, the life span of an API is important

0:15:35.009,0:15:38.180
to consider. It can be difficult to choose[br]how

0:15:38.180,0:15:40.629
you're going to version, or what your strategy[br]will

0:15:40.629,0:15:43.079
be, but you should approach it as if you

0:15:43.079,0:15:45.730
have to get the first one, the first version

0:15:45.730,0:15:49.660
of your API, absolutely right. It makes it[br]easier

0:15:49.660,0:15:51.999
down the road.

0:15:51.999,0:15:53.629
The most important thing, though, to remember,[br]is that

0:15:53.629,0:15:58.860
versioning is inevitable and plan for deprecation[br]from version

0:15:58.860,0:16:00.959
one.

0:16:00.959,0:16:05.319
I also like to think of APIs as if

0:16:05.319,0:16:08.670
they were a rescue dog. If anyone knows me

0:16:08.670,0:16:09.410
from Flat Iron School - I see a few

0:16:09.410,0:16:11.550
of you out there - I'm obsessed with rescue

0:16:11.550,0:16:14.129
animals. So I had to tie this back in

0:16:14.129,0:16:15.970
for a moment. So, this is not a West

0:16:15.970,0:16:19.910
Minister Kennel Club winning dog, but he's[br]more like

0:16:19.910,0:16:23.259
a little rescue pup. He has limitless potential[br]to

0:16:23.259,0:16:25.350
be an incredible pet if you let him get

0:16:25.350,0:16:27.509
there. Just like you want to set your future

0:16:27.509,0:16:29.999
dogs up for success, you'll want to do the

0:16:29.999,0:16:31.790
same for your API.

0:16:31.790,0:16:34.819
For starters, neither this dog nor your API[br]require

0:16:34.819,0:16:39.399
any fancy things. They simply crave repetition[br]and unconditional

0:16:39.399,0:16:42.410
support in order to be successful. Give them[br]what

0:16:42.410,0:16:45.139
they need to evolve into their new versions,[br]but

0:16:45.139,0:16:49.269
don't ever forget where they came from.

0:16:49.269,0:16:51.769
The JSON APIs is one standard for building[br]APIs

0:16:51.769,0:16:54.829
in JSON that is supported by the Rails community.

0:16:54.829,0:16:58.779
So, this is Steve Klabnik's quote. By following[br]shared

0:16:58.779,0:17:02.290
conventions you can increase productivity,[br]take advantage of generalized

0:17:02.290,0:17:06.790
tooling, and focus on what matters: your application.[br]And

0:17:06.790,0:17:09.929
we liked the JSON API standards, so I put

0:17:09.929,0:17:12.970
an example of it in here.

0:17:12.970,0:17:15.589
And like so many of the tools that we've

0:17:15.589,0:17:18.449
discussed already today, there are more out[br]there, and

0:17:18.449,0:17:20.130
there's a lot of great ones being developed[br]right

0:17:20.130,0:17:22.400
now. So Rosie's gonna share a few more of

0:17:22.400,0:17:26.200
those with you.

0:17:26.200,0:17:31.420
R.H.: So, building APIs is a shared problem[br]for

0:17:31.420,0:17:34.340
most developers. It seems there is now a general

0:17:34.340,0:17:37.600
shared understanding of what a good API should[br]consist

0:17:37.600,0:17:40.390
of. A shared solution is the next step. So

0:17:40.390,0:17:44.020
we can turn these best practices into conventions.

0:17:44.020,0:17:46.950
For the last couple of months, we've been[br]asking

0:17:46.950,0:17:49.330
every developer we encounter what they use[br]to build

0:17:49.330,0:17:53.770
APIs. The answers were usually Rails or Sinatra,[br]with

0:17:53.770,0:17:58.160
some combination of the tools available on[br]Ruby Toolbox,

0:17:58.160,0:18:02.260
and usually a partially hand-ruled solution.[br]We also heard,

0:18:02.260,0:18:04.120
more and more, how Rails is being used to

0:18:04.120,0:18:07.160
create a REST API that talks to a mobile

0:18:07.160,0:18:09.140
client, and there seemed to be growing interest[br]in

0:18:09.140,0:18:12.030
using Rails for JavaSrcipt frameworks.

0:18:12.030,0:18:14.830
These may not be traditional Rails applications,[br]but people

0:18:14.830,0:18:17.290
still recognize the value of Rails for creating[br]a

0:18:17.290,0:18:20.360
REST API.

0:18:20.360,0:18:23.910
After talking to lots of people, it was evident,

0:18:23.910,0:18:27.580
though, that an agreed upon solution still[br]wasn't clear,

0:18:27.580,0:18:29.470
and the whole thing just required way too[br]much

0:18:29.470,0:18:33.540
thinking. There's so many ways to hobble something[br]together,

0:18:33.540,0:18:35.650
but we wanted to know the Rails way. What

0:18:35.650,0:18:37.620
will be the Rails way to build a solid

0:18:37.620,0:18:38.050
API?

0:18:38.050,0:18:41.360
Again, damn it Rails, if you're so opinionated[br]and

0:18:41.360,0:18:43.700
committed to this idea of conventions, tell[br]me what

0:18:43.700,0:18:46.190
to do. We no longer have to be pioneers

0:18:46.190,0:18:48.690
venturing out into the unknown.

0:18:48.690,0:18:52.390
So, in the middle of all of these conversations,

0:18:52.390,0:18:54.510
we did see a Rails way emerging, though it's

0:18:54.510,0:18:57.490
not baked in yet. Lo and behold, there are

0:18:57.490,0:19:00.110
solutions emerging from the core Rails team[br]that provide

0:19:00.110,0:19:03.460
an opinion on how to create REST APIs. We've

0:19:03.460,0:19:07.520
been exploring Rails API in combination with[br]ActiveModel serializer

0:19:07.520,0:19:11.780
for building an API where you only need the

0:19:11.780,0:19:12.910
JSON end points.

0:19:12.910,0:19:16.030
Rails API is Rails. It utilizes most of the

0:19:16.030,0:19:19.120
same generators and conventions and will look[br]very, very

0:19:19.120,0:19:23.610
familiar. For this new generation of applications,[br]where the

0:19:23.610,0:19:26.570
API is your infrastructure that supports a[br]family of

0:19:26.570,0:19:29.550
client applications, we think this is what[br]the future

0:19:29.550,0:19:31.080
might look like.

0:19:31.080,0:19:34.920
So Rails API is really just a miniature Rails

0:19:34.920,0:19:37.160
stack, where they skipped all of the stuff[br]that

0:19:37.160,0:19:40.050
you need if you were creating views, producing[br]a

0:19:40.050,0:19:42.260
solution that is lighter and faster than the[br]full

0:19:42.260,0:19:44.450
Rails app. But it does still come with a

0:19:44.450,0:19:48.110
full suite of baked in solutions for many[br]poorly

0:19:48.110,0:19:51.230
understood problems.

0:19:51.230,0:19:53.040
And the documentation, there's a laundry list[br]of things

0:19:53.040,0:19:55.430
that are handled in the middleware layer and[br]the

0:19:55.430,0:19:59.020
ActionPack layer. This is definitely a win.[br]For example,

0:19:59.020,0:20:02.240
you might understand perfectly how to handroll[br]a solution

0:20:02.240,0:20:06.120
for IP spoofing attacks, or maybe not. But[br]even

0:20:06.120,0:20:07.890
if you do, why spend time doing this if

0:20:07.890,0:20:11.880
Rails is gonna do it for you? Thanks Rails.

0:20:11.880,0:20:14.180
And again, if there's a solution for something[br]already

0:20:14.180,0:20:19.560
out there, I'd rather use that than reinvent[br]the

0:20:19.560,0:20:20.080
wheel.

0:20:20.080,0:20:23.130
The other tool we're exploring is ActiveModel[br]serializers, and

0:20:23.130,0:20:28.070
sure, serializers replace hash-driven development[br]with object-oriented development. For

0:20:28.070,0:20:32.170
example, with AcitveModel serializers, when[br]you're using render JSON

0:20:32.170,0:20:35.370
in your controllers, Rails will search for[br]a serializer

0:20:35.370,0:20:38.320
before, for the object and use it if available.

0:20:38.320,0:20:42.180
It's an elegant solution to creating server-side[br]APIs that

0:20:42.180,0:20:46.410
doesn't require a view layer.

0:20:46.410,0:20:48.650
They act a lot, serializers act a lot like

0:20:48.650,0:20:52.620
models and can be easily customized. ActiveModel[br]serializers also

0:20:52.620,0:20:57.020
follows the JSON API standard, so you know[br]you're

0:20:57.020,0:20:59.890
creating a standardized API that will easily[br]talk to

0:20:59.890,0:21:03.440
a variety of clients.

0:21:03.440,0:21:05.260
It really helps to take the guessing out of

0:21:05.260,0:21:07.800
how your JSON API should be structured.

0:21:07.800,0:21:12.770
OK. So, it's time to start wrapping things[br]up.

0:21:12.770,0:21:15.490
A few points to leave you, leave everyone[br]with.

0:21:15.490,0:21:19.190
We find it's increasingly important to design[br]APIs following

0:21:19.190,0:21:22.880
patterns and conventions that fit into the[br]system as

0:21:22.880,0:21:25.310
a whole. To do this, we can leverage existing

0:21:25.310,0:21:28.870
best practices and tools, and by doing so[br]we'll

0:21:28.870,0:21:32.030
create APIs that support a more organized[br]structure for

0:21:32.030,0:21:34.200
our applications.

0:21:34.200,0:21:37.530
I was inspired by Yehuda Katz's keynote yesterday,[br]and

0:21:37.530,0:21:39.840
I think it's time for us as a community

0:21:39.840,0:21:43.140
to move API design out of the area of

0:21:43.140,0:21:48.080
experimentation and into the area of collective[br]shared solution.

0:21:48.080,0:21:51.180
We'll all benefit.

0:21:51.180,0:21:55.450
And again, trivial choices are the enemy.[br]Drink your

0:21:55.450,0:21:59.430
convention over configuration Kool-Aid. But[br]brush your teeth afterwards.

0:21:59.430,0:22:03.930
Kool-Aid's not good for you. Anyway. We're[br]often trying

0:22:03.930,0:22:06.000
to solve the same problem. And when this is

0:22:06.000,0:22:08.700
the case, we should agree on a strong convention

0:22:08.700,0:22:10.850
and all follow it.

0:22:10.850,0:22:14.160
We'll all benefit in the end. And third, don't

0:22:14.160,0:22:16.380
forget about who or what else is going to

0:22:16.380,0:22:18.850
want to use this API in the future, and

0:22:18.850,0:22:23.270
plan accordingly. This may include native[br]mobile applications or

0:22:23.270,0:22:26.660
a JavaScript client-side framework or something[br]else that we

0:22:26.660,0:22:30.030
haven't even imagined yet. By designing our[br]APIs today

0:22:30.030,0:22:33.040
to be consistent across platforms, we can[br]make changes

0:22:33.040,0:22:38.090
to our client-side applications in the future[br]much easier.

0:22:38.090,0:22:40.760
So tomorrow, someone's not trying to use your[br]hand-ruled

0:22:40.760,0:22:44.090
API that didn't really follow any established[br]design patterns

0:22:44.090,0:22:47.360
or conventions, and you have to explain that,[br]well,

0:22:47.360,0:22:49.430
it seemed like a good idea at the time.

0:22:49.430,0:22:51.810
For those of you who aren't from Minneapolis,[br]this

0:22:51.810,0:22:55.030
is the ugliest building in the Minneapolis[br]skyline. So.

0:22:55.030,0:22:58.510
A little context for you. We all drive by

0:22:58.510,0:23:01.640
and shake our heads. Like oh, why?

0:23:01.640,0:23:06.080
Or worse. Your application gets scrapped because[br]it was

0:23:06.080,0:23:09.820
poorly organized from the get-go and too rigid[br]to

0:23:09.820,0:23:11.320
update.

0:23:11.320,0:23:15.750
And last, but not least, document all the[br]things.

0:23:15.750,0:23:19.390
Documentation is the cool to API being used[br]successfully.

0:23:19.390,0:23:24.460
All right. And we've come to the end. I

0:23:24.460,0:23:26.820
hope, just want to leave you with one thought.

0:23:26.820,0:23:28.870
I hope when you approach your next project,[br]you'll

0:23:28.870,0:23:30.320
consider building your API first.

0:23:30.320,0:23:33.030
S.H.: All right, thanks everybody.