Bummer! This is just a preview. You need to be signed in with a Pro account to view the entire video.
Start a free Basic trial
to watch this video
Designing Irresistible APIs
43:10 with Kirsten HunterWhen creating a new REST platform, the planning process frequently gets skipped (or is misunderstood) resulting in an ill-conceived API. I'll walk you through the steps needed to create an API that developers love, and point out the common traps to avoid. The presentation will cover creating user stories, deciding on metrics, planning the API, design decisions, documentation and developer support. I will focus on teaching you how to create a developer experience that will delight and amaze your developer partners and increase engagement with your platform. This talk will focus on higher level choices rather than HTTP architecture, and is appropriate for developers, product managers, or anyone else with an interest in achieving success for their API program. The Open API Ecosystem is an amazing opportunity for companies to partner with developers, but you really only get one chance to impress, so come learn how to make your company's API an "A List" destination. What should the audience expect to learn from your talk?: *API Developer Experience *API Use Cases *Measuring Success
-
0:01
Okay, everybody, I'm gonna go ahead and get started.
-
0:04
I'm Kirsten Hunter.
-
0:05
I'll be talking about designing irresistible APIs.
-
0:08
For those of you who came to my workshop yesterday,
-
0:10
a lot of this is gonna look familiar to you.
-
0:13
But this is much more focused on the producer side.
-
0:16
Creating APIs that are gonna make
-
0:17
your developers happy, creating a successful API.
-
0:22
One of the main reasons I like to give this talk
-
0:25
is I gave a talk at OSCon a couple of years ago.
-
0:29
And someone ask, asks me a question about about performance and scalability.
-
0:35
And my answer was, if you don't make it a usable API,
-
0:40
nobody's gonna use it, and then you won't have to worry about scalability.
-
0:43
So, what I'm gonna do is I'm gonna try to help you understand
-
0:48
the things that you need to think about when you're creating an API.
-
0:51
So that you don't fall into some of the pitfalls that other companies have had.
-
0:56
I've been working with APIs for about ten years.
-
0:59
I worked at LinkedIn, I worked at Netflix, I've spent a lot of time supporting
-
1:06
developers and partners and trying to help them be successful with APIs.
-
1:10
So this is all based on problems I've seen with fairly large-scale APIs,
-
1:17
and I'm trying to give you the information about how to be successful.
-
1:25
My presentation style.
-
1:26
I'm using Haiku Deck.
-
1:27
It's a fantastic program.
-
1:30
It's an iPad app.
-
1:32
You'll see there will be pretty pictures.
-
1:34
That are sort of evocative and give you something to think about.
-
1:39
And there's just a few words.
-
1:41
I will make speaker notes when I put this on SlideShare, so that even
-
1:45
without my interpretive dance you can understand
-
1:47
what it was I was talking about.
-
1:49
When I put a lot of information and bullets on
-
1:51
the slides, what happens is, I talk a lot faster.
-
1:56
I read the slides to you, you read the slides.
-
1:59
And then it's like story time, and we all fall asleep.
-
2:02
So, what I want you to do, is I want you to listen to me.
-
2:06
And I also want you to ask questions.
-
2:09
I, I love making sure that the information I'm giving you is valuable to you.
-
2:14
So, at any time, you can raise you hand and ask questions.
-
2:17
There should be time at the end as well.
-
2:20
My handle on twitter is Synedra, S-Y-N-E-D-R-A.
-
2:26
And you're welcome to tweet you're welcome to ask me questions anytime after this, at
-
2:32
the conference or send me a tweet or an email and I'll be happy to help.
-
2:37
Okay, so, why do you wanna have an API?
-
2:42
A lot of the time what people hear is their VP says we need an API.
-
2:49
And so when asked someone asks you why you have
-
2:51
an API, the answer is cuz we wanna have an API.
-
2:55
Okay, so but a lot of companies have gone that route.
-
2:59
Netflix had the idea of, let a thousand flowers bloom.
-
3:02
If we make an API, people will use it.
-
3:05
It turns out, if you don't have a
-
3:07
directed strategy, if you don't know what the business
-
3:10
value is for your API, eventually someone in the
-
3:13
C-suite is gonna say what are those engineers doing?
-
3:15
And why?
-
3:17
If you can't answer that question, then you're, it's very possible
-
3:22
that your API will be killed or throttled back a lot.
-
3:27
It also makes it harder for you to communicate with your developers.
-
3:30
How you want the to use the API, what you want them to do with the API.
-
3:34
So thinking about that stuff ahead of time allows you
-
3:36
to make an API but is useful for your users
-
3:40
and also that you can defend to your management when
-
3:43
they ask you why it is that you have the API.
-
3:47
So I'm going to go over a few business cases
-
3:49
so you can understand what the sort of range is.
-
3:53
Mobile/Market Penetration.
-
3:57
so, getting yourself on mobile, getting market penetration.
-
4:01
Netflix is actually a great example of this.
-
4:04
Not the mobile exactly, but if you buy a device, a television, a DVD
-
4:10
player, a Roku pretty much anything but an Apple TV, it's gonna have Netflix on it.
-
4:15
It might have other things, it might have Amazon on it.
-
4:18
But Amazon has to work a lot harder,
-
4:20
because everybody expects Netflix to be on those devices.
-
4:23
Because they were there, they really pushed,
-
4:27
they work hard with their copartners to
-
4:28
make sure that they are the de
-
4:30
facto standard for streaming movies on these devices.
-
4:35
Drive Usage.
-
4:36
Twitter Twitter lets you use their website.
-
4:40
They like you to use their client, their mobile client, but
-
4:45
what they want is all the content that they can get.
-
4:48
They want people to engage with the content and retweet it.
-
4:51
They want you to share stuff that you find elsewhere.
-
4:55
There's a reason that there's little Twitter buttons, share on Twitter buttons.
-
4:58
There's a reason why they make it so
-
5:01
easy for developers to integrate Twitter into their application.
-
5:06
One of the things that they do is they, they do identity management which allows
-
5:12
more people to use Twitter, and then start adding to the, to the feed.
-
5:17
Adding good quality content about what people are thinking.
-
5:21
Defensive Strategy.
-
5:23
Okay, so this is, I'm, the example I'm gonna get, give is not exactly about APIs.
-
5:28
I can give you an API example which is Best Buy.
-
5:31
They wanted to protect themselves from Amazon
-
5:36
selling everybody all over the internet electronics.
-
5:39
With a Best Buy API you can see what's available.
-
5:42
You can sort of shop for things.
-
5:44
You can, and it's all very focused on electronics.
-
5:49
Circuit City didn't do that.
-
5:52
So who's doing better now?
-
5:55
And book, the bookstores are another great example.
-
5:58
So Amazon came along.
-
6:00
And Borders was like, yeah, whatever.
-
6:02
That internet thing is never gonna pan out.
-
6:04
No one's gonna do anything with that.
-
6:07
Barnes and Noble did a slightly better job.
-
6:09
They have the Nook, they sort of embraced
-
6:12
the e-book, as something that was important to them.
-
6:15
And they did put energy into their website.
-
6:20
So, now where's Borders?
-
6:23
they, they got eaten, by the people who were thinking about
-
6:27
what people were gonna be doing in the next few years.
-
6:31
Partner connectivity.
-
6:33
I cannot stress enough how important this is.
-
6:38
Federal Express FedEx has a lot of
-
6:43
competition, the US Postal Service, UPS DHL.
-
6:46
There's lots of people who will deliver stuff for you.
-
6:51
But FedEx was the first one to have a really good API.
-
6:56
Once you have caused a, a partner to integrate
-
6:59
with your system, with your API, they're kind of trapped.
-
7:04
I mean they could go, but there's more friction.
-
7:06
It's a little harder for them to leave.
-
7:09
and, and it's, this is a huge value for your business.
-
7:11
This might be the only value in your API, and it's huge.
-
7:15
If you can keep your big partners happy, and you can keep them connected to you,
-
7:20
and make it hard for them to leave, then your company's gonna do a lot better.
-
7:27
So, technical cases, Abstraction.
-
7:30
Reducing complexity.
-
7:33
In SendGrid, mail is really hard.
-
7:37
Sending mail, there's a lot of different
-
7:38
formatting issues, there's a lot of different clients.
-
7:42
So SendGrid makes email easy and
-
7:45
that's, that's their business, their technical case.
-
7:50
Simplify.
-
7:51
So Context.io also works with email.
-
7:54
What they do is they work on the client end.
-
7:56
So, if you have Gmail for instance, your ability to organize, and have activities
-
8:01
based on the information that comes into your email is, is limited.
-
8:06
Contacts.io I know allows you to make, make, make
-
8:11
applications that work with the things in your email box.
-
8:16
One of the hacks that I keep, keep threatening to make, that I
-
8:20
think would be hilarious, is, I wanna use contacts.io to look at my email.
-
8:26
And if one of my relatives sends me something that's on snopes
-
8:29
or an email that says, here's a chain letter send recipes to
-
8:34
all these ten people, put your name at the bottom, take the
-
8:36
name off the top, or you're going to burn in hell forever.
-
8:41
I don't want to see that email.
-
8:44
I want it to just leave my mailbox.
-
8:46
And then I would like it to use Twilio to call them at
-
8:49
3 o'clock the next morning with a very important message about email etiquette.
-
8:54
That's how annoying it is to me.
-
8:56
[LAUGH] probably that annoying to you guys as well.
-
9:00
Metered Usage.
-
9:01
Amazon, Heroku, these are companies where they charge
-
9:06
you based on how much you use the system.
-
9:09
This is actually a really great model for developers to use.
-
9:14
It's great that something is free, Heroku desk
-
9:16
have free tear for a very small amount
-
9:18
of usage, which makes them great prototyping and
-
9:21
having a system that is visible to the internet.
-
9:24
Amazon has, they charge you for how much
-
9:29
you use the S3 or the or the, the
-
9:35
service or whichever part of AWS you're using.
-
9:41
So this is a, this is, this is actually a modernization strategy.
-
9:45
You'll notice I haven't talked a lot about modernization strategies.
-
9:48
And part of that is because well, Twilio and SendGrid, or SendGrid and ContextIO
-
9:55
and Amazon do have monetization strategies that are kind of centered around the API.
-
10:01
I still say that partner connectivity and some of
-
10:03
the other values are just as important for your company.
-
10:08
So, even if your API's not making money, that's cool as
-
10:12
long as it's contributing to the stability or growth of your company.
-
10:18
Okay.
-
10:18
All of the above.
-
10:19
So, Twilio.
-
10:21
Twilio will send SMSs, they have metered usage.
-
10:26
They make things, hard, hard things.
-
10:30
voice, and, and SMS are actually very hard things to do without an API.
-
10:34
But also have a, an army of evangelists that
-
10:39
run around to techathons and help people do it.
-
10:42
And they have one of the best developer experiences out there.
-
10:46
Their goal is, if you go to their developer site
-
10:50
you can make a call, a successful call within five minutes.
-
10:54
If they don't meet that metric, they try to make their documentation better.
-
10:57
So, Twilio's money, monetization strategy is their API.
-
11:03
They don't have any other way of making money,
-
11:06
They are developer evangelists working in the marketing group.
-
11:10
But so that's another sort of technical case.
-
11:16
When you're building an API there are eight architectural considerations.
-
11:20
Affordances, what do you want people to do with your API.
-
11:24
You need to think about what, what kind of client do you want people to make.
-
11:31
Are you trying to make some internal clients and some external clients?
-
11:35
Are you going to have a website and, and mobile and that's it?
-
11:38
You need to understand what is important to you.
-
11:41
If you're trying to drive usage, then you should make
-
11:44
sure that it's super easy for people to drive usage.
-
11:47
I'm going through these things kind of quickly, because I'm
-
11:52
gonna, at the end, sort of give you a process that you can use to
-
11:58
take these ideas and create an API that is useful, meaningful, and successful.
-
12:05
Your Schema.
-
12:07
It's not as important as it seems, I think
-
12:13
of the schema as important only in that modeling
-
12:16
your schema deliberately and explicitly, allows you to see
-
12:21
where there are holes, where you are being inconsistent.
-
12:24
You want your system to be consistent, easy to use, and, and complete.
-
12:30
And it's okay for your schema to
-
12:32
have to-dos, just like in test-driven development.
-
12:34
It's okay to say, when we get around to doing
-
12:37
the profile stuff for the users, it should have this architecture.
-
12:44
In terms of, of, how to organize them,
-
12:49
I do tend to like it when resources are two levels deep.
-
12:56
So five plus or minus two is is the amount that people can remember.
-
13:01
So, you know, three to seven top level buckets and then the things underneath.
-
13:07
That's actually not important for the usability of your API, but it's
-
13:11
important for the developers to kind
-
13:13
of understand how your information is structured.
-
13:16
And how to think about, creating a product from your API.
-
13:23
[SOUND] Who Can Do What?
-
13:25
.
-
13:26
Okay, a lot of times, people mix up authentication and authorization.
-
13:33
They use the same word for the sa, both different things.
-
13:36
So, if I have a driver's license that says I'm 19, that's great.
-
13:42
It, it identifies me, it's a thing.
-
13:44
And can I buy cigarettes.
-
13:47
But I can't buy alcohol.
-
13:48
All right, so, I'm not authorized to do all of
-
13:52
the things that someone else with a different ID can do.
-
13:55
There's different ways to do authentication.
-
13:58
OF allows the user to use an identity that they've
-
14:02
established elsewhere and give you permission to act on their behalf.
-
14:06
In your application.
-
14:09
One of the things that people don't realize is if,
-
14:12
if identity isn't one of your core competencies, if you're
-
14:15
not super worried about security and privacy, it's sort of
-
14:19
a fun application, you can actually use some of these providers.
-
14:23
LinkedIn, Facebook, Twitter, you can log in with, a lot of people log in
-
14:30
with those services, even if you're not interacting with them in any other way.
-
14:34
This allows you to focus on the core, competencies of your application.
-
14:40
The more things that you can outsource to other systems, especially
-
14:44
when you're trying to get, first thing out the door, the better.
-
14:50
authentication, and authorization, it can be things you can do.
-
14:55
But it also can be
-
14:59
how many times you can do them.
-
15:01
So, most APIs have throttling limits.
-
15:05
Those throttling limits are based on a couple of factors from the business side.
-
15:10
Search is usually throttled for a couple of reasons, and
-
15:13
it's usually more heavily throttled than any of the other resources.
-
15:17
One reason is it's expensive.
-
15:20
You can't really cache search results.
-
15:22
People are going to search on new things.
-
15:25
So it's going to hit the server every time.
-
15:27
And that's the same search server that you probably use for your main product.
-
15:31
So you have to be pretty protective of that
-
15:33
and make sure that people aren't abusing that resource.
-
15:37
You don't want to bring down your main product by, by third party actors.
-
15:44
But the second reason, and something you need to realize,
-
15:48
especially if you are working with you know, the C suite.
-
15:53
This helps you protect your data, your data is likely your intellectual
-
15:59
property, the thing that makes your, your system important to people.
-
16:04
So by limiting the number of times people can do searches you make it
-
16:09
much more difficult for people to rebuild
-
16:11
your database elsewhere and compete with your product.
-
16:15
Sales people will generally think that if you have an API, everyone
-
16:18
is going to steal all your data and make a competing product.
-
16:22
That's very rarely the case.
-
16:23
If someone wants to do that, they'll scrape.
-
16:27
and, there's ways to get around that, but, the
-
16:30
API is not actually a vulnerability in this case.
-
16:33
[SOUND] So, building a successful API.
-
16:39
First, your API is a product.
-
16:42
Your API needs to be a first-class product.
-
16:45
You need to treat it like, as, as,
-
16:48
as something that's as important as your other product.
-
16:51
You need to not try to slap it on.
-
16:55
Okay so, a lot of times especially in really big
-
16:59
organizations what happens is people say, oh we need APIs.
-
17:02
So what we're gonna do is every time a developer makes
-
17:06
a thing, not only do they have to make documentation which
-
17:08
they don't wanna do or tests which they really don't wanna
-
17:12
make, but also they now they have to make an API.
-
17:16
So usually, they'll like shove it through some library that spits out an API
-
17:19
that doesn't really have a purpose other than being a check box for that developer.
-
17:24
That developer's not thinking about the end
-
17:27
user, use case, they're just thinking about
-
17:30
making an API because that's on the list of things they have to do.
-
17:34
They're being measured on writing code.
-
17:37
Usually they are measured on the quality of there documentation or tests, and
-
17:41
when we have APIs, they are usually not measured on the value of those.
-
17:46
So we end up with a potato and a bunch of really
-
17:50
ugly sprouts, that are not related to each other in any way.
-
17:54
It's hard to use, it's ugly, and it's not going to be successful.
-
17:59
I'm gonna talk about API First.
-
18:03
You'll all be like I can't do that.
-
18:06
API First is the idea that everything your company does should go through APIs.
-
18:13
Your website, your mobile devices, any other products, your
-
18:17
API should be the point of truth for your company.
-
18:22
That means that if you add a feature to your website, your
-
18:26
API has access to it as well, your mobile device automatically has it.
-
18:30
You don't have duplicate code in two different places.
-
18:33
Worse, is, the, the, the worst part is
-
18:36
that usually, the duplicate code isn't exactly the same.
-
18:41
so, the API does things slightly differently and when there's a bug
-
18:44
in the website, there's probably a similar bug on the API side.
-
18:48
But but it doesn't get it doesn't get fixed.
-
18:54
I, I refer to places where the API is not a first class product.
-
19:00
People who don't use API First as, worlds
-
19:05
where the, the API is, is sucking hind tit.
-
19:08
It's the ninth puppy, there's no milk.
-
19:12
It has to wait its turn.
-
19:13
And the idea is, developer makes a new feature on the website, great.
-
19:18
The product is good.
-
19:19
And then when he has time, do himself, extra
-
19:24
spare time as all developers do, all the time.
-
19:27
He's gonna go over and make a meaningful API that meets that same future need.
-
19:32
That doesn't happen, it's not reasonable.
-
19:36
And whenever you try to slap an API on as a side thing.
-
19:42
You're going to end up with bugs.
-
19:44
You're going to end up with a very difficult to maintain
-
19:48
API and it's not going to work as well as you'd like.
-
19:53
So the first thing you want to do is figure out what your Business Value is.
-
19:57
So I talked about a few different things driving usage.
-
20:00
Do you want people to.
-
20:01
Interact with your system more often.
-
20:03
If it's a social s, sorta site then
-
20:05
yeah, you probably want people to access the system.
-
20:09
And, and learn, and, and read and, and write to it.
-
20:12
So that might be the business value.
-
20:15
Getting new users, that's, that's a value.
-
20:19
All, always think about those partners.
-
20:22
If you wanna be a successful company, you're gonna need to
-
20:25
partner with and really support some of the larger companies like Microsoft.
-
20:31
Microsoft, expects well formed APIs.
-
20:35
They're very smart.
-
20:36
they, they push really hard.
-
20:39
So, depending on your business value.
-
20:43
I mean this is what should happen if you
-
20:44
stand in the elevator with the CEO for 11 seconds.
-
20:47
And he says, hey what is it, we have API for anyways.
-
20:51
Partner integration.
-
20:53
Driving usage.
-
20:55
Modernization is rarely what you want from your API,
-
20:59
but if you have a plan for that, that's great.
-
21:02
So you have to have a business value.
-
21:05
And from that business value, you make some use cases.
-
21:10
If one of your use cases is mobile, that rest potato, is not going to work.
-
21:18
Because what that rest potato usually ends up
-
21:21
being is your database schema barfed into REST.
-
21:27
And a mobile developer wants to make one call per screen.
-
21:33
They have to deal with the fact that a user's
-
21:35
gonna walk into an elevator, or drive into a tunnel.
-
21:38
So they can do a retry if they're making
-
21:40
one call to get all the information for a screen.
-
21:42
But they are not going to want to make
-
21:45
50 calls to get all the information they need.
-
21:48
So, figure out what your use cases are, what they have to look like.
-
21:53
Those are the things that should be super easy to do with your API.
-
21:57
I'm gonna tell you here, following the REST guidelines as you
-
22:00
understand them is not necessarily going to be what you want.
-
22:04
You need to understand what your customers want.
-
22:06
You need to think like your end users.
-
22:08
And you need to have use cases
-
22:10
that you understand and that your developers understand.
-
22:15
And then here is another thing that's gonna help you with that C-suite.
-
22:20
Measure success.
-
22:22
What metric are you using to measure success?
-
22:25
Your business value is usage.
-
22:28
Great, count how many times people do things on the API.
-
22:33
Your API is gonna be cheaper than the website.
-
22:35
If, if there's a configuration, a form on your website.
-
22:40
And you have an API, maybe what you're gonna measure is what
-
22:43
percentage of, of changes to the configuration are made by the API.
-
22:49
And maybe we're gonna try to drive more to the API.
-
22:52
It's cheaper, it's actually easier for your partners to automate.
-
22:55
And when I say partners in this case I'm also talking about third party developers.
-
23:01
You wanna, even if they don't have a, a
-
23:04
monetary contract with you, you wanna treat them like partners.
-
23:11
copy.
-
23:12
There's some really fantastic APIs out there.
-
23:15
They might not be exactly like yours, but you can
-
23:19
learn a lot by looking at APIs that are successful.
-
23:22
Twitter's a great example.
-
23:23
They're, they're developer portal is really strong.
-
23:28
Sometimes you want to have authentication and the best
-
23:32
way to do that is to use existing libraries.
-
23:35
Don't try to build everything from scratch.
-
23:39
Go ahead and use other API's if you need to.
-
23:42
Just be aware of the vul, vulnerability that you have and have
-
23:46
a strategy for what you will do if that API goes away.
-
23:51
The developer experience.
-
23:53
This is one of the things that will drive the success of your API.
-
23:57
And I'm not just talking about external APIs, I'm talking about internal APIs.
-
24:02
Even, I would say it's even more important for internal APIs.
-
24:06
Because if someone is forced to use your API and it's a difficult experience.
-
24:12
They're still forced to use your API and you're gonna have
-
24:15
a lot of support debt that you'll have to deal with.
-
24:19
You want to document it.
-
24:20
You want to make it so that most of the time they can just do what they want.
-
24:24
It's quick, it's easy and they don't talk to you.
-
24:27
When you have open developers what you have to remember is
-
24:32
that open developers are like wild animals on the Savannah.
-
24:37
Wandering around looking for a watering hole.
-
24:40
So they're gonna give you about five minutes.
-
24:42
They're gonna come in, they're gonna think, What?
-
24:46
But, what is this thing?
-
24:47
What can I do, and how can I do it?
-
24:51
And why, like, what problem can I solve with this?
-
24:55
You need to make those things really easy to understand.
-
24:58
And again, Twitter does a really good job of this.
-
25:00
Twilio does as well.
-
25:02
And, I encourage you to look at some successful
-
25:04
developer portals to help make a great developer experience.
-
25:11
Communication.
-
25:13
So communicating with your developers is critical.
-
25:18
Don't just tell them what your API does.
-
25:22
You know what your business value is.
-
25:23
You know how you're gonna measure it.
-
25:25
You know what your use cases are.
-
25:26
Those three pieces of information are not going to
-
25:31
sync your company if you share them with the developers.
-
25:34
On the other hand, what they're going to do is they're
-
25:36
going to convince those developers that you have thought about this API.
-
25:39
You have plans for this API.
-
25:41
This API is a real product.
-
25:43
They can use it.
-
25:45
They can trust you.
-
25:47
There have been many cases in the past where
-
25:50
people have made APIs without a real good strategy.
-
25:53
And then people used it and they sorta made modernization things.
-
25:56
And then, the API got shifted or pivoted or whatever, and
-
26:00
all of a sudden it wasn't available for the developers anymore.
-
26:05
So the developers who had invested their time in
-
26:08
using this API were kinda shot in the foot.
-
26:11
So you need to build that trust.
-
26:14
And one of the best ways to build that trust
-
26:18
is to tell the developers why you have an API.
-
26:22
How you're measuring success.
-
26:23
What you're trying to accomplish with it.
-
26:25
Show them the use cases.
-
26:27
Make those tutorials.
-
26:28
Give them example code that works.
-
26:31
In as many languages as you can.
-
26:33
Encourage your community to do that as well.
-
26:38
Marketing to developers is different than marketing to regular people.
-
26:43
Regular people, you show them a pretty picture of
-
26:45
a ketchup bottle or whatever, and they're like, [NOISE], ketchup.
-
26:49
Or bacon, bacon's always awesome.
-
26:54
Developers want to feel engaged.
-
26:57
Most of them are gamers of some sort.
-
27:00
They enjoy leveling up.
-
27:02
They enjoy feeling like they've accomplished something.
-
27:05
It's one of the reasons I think Twilio has such a great onboarding experience.
-
27:09
They want, within five minutes, for you to have done a thing.
-
27:13
Created a call that works.
-
27:15
Because now, what's happened?
-
27:17
You're invested in, in the API.
-
27:20
So that five minutes that you were gonna give
-
27:22
them, now it's turned into a half an hour.
-
27:25
And they, the more it feels like play.
-
27:30
The more likely they are to stay.
-
27:32
The more it feels like work the more likely they are to go do something else.
-
27:36
I wanna give a shout out to Firebase.
-
27:39
They have a great tutorial system for learning how to use the system.
-
27:45
It feels a lot like Codecademy.
-
27:47
It's it's very step by step.
-
27:53
When you make a documentation, you also want to think
-
27:56
about how the developers are going to get to that documentation.
-
28:00
So for instance, Hiroko.
-
28:04
Which is a fantastic product.
-
28:07
All their tutorials are about 17 pages.
-
28:11
Just a whole list of how to do things.
-
28:14
It's exhausting.
-
28:17
And the problem that I have had is that I can get through about maybe a third of it.
-
28:24
And then, something that I, in my real life comes and I have to deal with it.
-
28:28
And then I go back and I don't know where I was.
-
28:30
So break it up into chunks.
-
28:33
Have tasks.
-
28:35
And at the end of the task, it may seem
-
28:36
really stupid, but be like woo-hoo, you did a thing.
-
28:39
Now you can go on to the next thing.
-
28:41
Make a choose your own adventure.
-
28:42
Make it feel like they're advancing down a path.
-
28:48
When you look at the 17-page tutorial, you don't feel like you've
-
28:50
accomplished anything until you get to the bottom of the 17th page.
-
28:54
That's a little demoralizing, and it sure doesn't feel fun.
-
29:00
Tools.
-
29:02
There's some great tools out there for API exploration,
-
29:06
IOdocs, swagger if you have your database schema modeled,
-
29:13
effigy has a console.
-
29:15
It doesn't really matter how, but you need to make
-
29:17
it easy for people to see what a call looks like.
-
29:23
there's, there's also Runscope, which allows you to
-
29:26
sorta watch how traffic works on arbitrary APIs.
-
29:30
And API tools from 3scale [UNKNOWN] can do the same thing.
-
29:35
So, figure out how tools can be used.
-
29:38
Give people little, little how to do it guides.
-
29:43
So that they can explore and see what they
-
29:46
can do with your API without having to write code.
-
29:51
Asking questions.
-
29:53
So this is not your problem as a producer, except you're supporting the developer.
-
29:59
So one of the things software overflow actually has
-
30:03
a page that tells you how to ask good questions.
-
30:06
And it's not quite clear enough.
-
30:08
So I try to communicate to anyone I'm
-
30:12
trying to support what a good question looks like.
-
30:15
And a good question looks like a good bug report.
-
30:18
And it is.
-
30:20
I did x.
-
30:21
I expected y to happen.
-
30:24
To my dismay, z happened instead.
-
30:27
A good question always has all three of those things.
-
30:30
And the reason, you'd think, well, okay, I, I get the, I get the A and C thing.
-
30:36
Like I did this and that happened.
-
30:38
A lot of times your users will be
-
30:40
really frustrated, and they'll be like, it crashed.
-
30:44
Okay, well, well, what were you doing at the time?
-
30:49
And then they'll tell you, well, I did this and it crashed.
-
30:52
And you're like yeah, that's, that's actually.
-
30:55
That's what I would expect that to happen.
-
30:57
So you want to know what they did,
-
31:00
what their expectation was, and what the result was.
-
31:04
Maybe there's a bug.
-
31:05
Maybe they're using a different resource than they should be using.
-
31:09
The example I give so you can understand the
-
31:12
importance of this is, I jumped off a cliff.
-
31:15
I expected to sprout wings and fly.
-
31:18
To my dismay, I plunged to my death instead.
-
31:21
Okay, not a bug in gravity.
-
31:23
A problem with my expectations.
-
31:26
But when you communicate with your developers about asking questions,
-
31:29
you want to tell them, if they have an incorrect expectation.
-
31:33
That's a problem.
-
31:35
It's a, probably a documentation problem.
-
31:36
A communication problem.
-
31:38
You should have made sure that they understood what was going to happen.
-
31:41
So encourage them to understand that they're not
-
31:45
stupid because they're expecting the wrong thing to happen.
-
31:49
You just didn't tell them what was gonna happen.
-
31:51
So you'll fix
-
31:54
that.
-
31:55
SDKS.
-
31:55
All right, John Chian is gonna talk later, he's probably gonna talk about them.
-
32:00
I do not like SDKS.
-
32:03
For API's.
-
32:05
And the reason is if your API needs an SDK, you're doing it wrong.
-
32:11
You're API is not well formatted.
-
32:13
It is not created well.
-
32:14
It's not easy to use.
-
32:16
The more levels of abstraction you put between the user and
-
32:19
your API, the more places a, a of potential failure there are.
-
32:23
And, and it's, if you created a good API you don't need an SDK.
-
32:32
And also once you start making SDKs you
-
32:36
have incurred a huge amount of technical debt.
-
32:38
Because every time you change your API you have to change all
-
32:43
12 of the SDKs you have for all of the different languages.
-
32:46
Make is so that someone can write code in a, in any language HTTP
-
32:52
is well supported in, in all modern programing languages.
-
32:58
Make your example show them how to use just a basic call.
-
33:02
You may have to give them some help with
-
33:03
authentication, that is a hard thing to deal with.
-
33:08
But don't, don't try to wrap the whole API in
-
33:12
an SDK so that they aren't actually touching your, your API.
-
33:17
Because you're gonna end up supporting two sets
-
33:19
of things, and, and it's gonna slow you down.
-
33:24
And it's basically just evidence that you didn't
-
33:28
do a fantastic job of creating your idea.
-
33:33
Okay, so just like anywhere in the on the
-
33:38
internet intelligent conversation ends when a cat picture is posted.
-
33:44
So this is my cat picture.
-
33:46
And I will open up the floor to questions.
-
33:50
Again you guys can tweet me or you can ask me pretty much anything about API's.
-
33:56
When I say I worked with them for
-
33:57
ten years, I've worked with them for ten years.
-
33:59
I have seen everything on the consumer side and the producer side.
-
34:04
And I probably have an opinion.
-
34:05
[LAUGH] But I'll share it with you.
-
34:07
So, are there any questions?
-
34:11
Yes.
-
34:12
>> Do you have any wisdom versioning
-
34:14
an API or rereleasing versions with recent changes,.
-
34:18
How do you, kinda deal with that from a, from [INAUDIBLE] aspect.
-
34:21
>> So there's a few different ways to deal with versioning.
-
34:24
So people put a version in the URL.
-
34:27
Some people put it as a header.
-
34:30
Some people put it as a parameter.
-
34:33
How you do it is not important.
-
34:36
That you communicate it clearly to your users is important.
-
34:40
I caution against putting things in headers when you have a large group
-
34:45
of people who are not fantastic developers because it is hard.
-
34:51
In a lot of languages.
-
34:53
One of the problems that I had at at Netflix was that
-
34:56
someone wanted to use the Zend framework, which is a PHP framework.
-
35:00
And it made it pretty much impossible to add headers.
-
35:03
So that's how you can set versions and what I tend to think the best
-
35:09
strategy is, is to have your default, like have a, not use the URL.
-
35:16
But have a default.
-
35:17
And tell people when you're going to change the default, and
-
35:20
tell them how to go, how to keep using the older version.
-
35:24
Move the default forward to the new version.
-
35:28
So that new people get the new version, and
-
35:30
the old people can keep using the old version.
-
35:33
I'm frequently asked how to get people to move from
-
35:36
the old versions so they can get rid of it.
-
35:39
That's pretty much impossible.
-
35:42
Somebody had a task six months ago, they fixed, they, they, they met that task.
-
35:49
By using the first version of your API.
-
35:51
They have no interest in going back and writing more code.
-
35:55
They, they probably have forgotten how the code works at all.
-
35:59
And you can't push them.
-
36:01
But what you can do, is you can try to pull them.
-
36:05
Maybe version three of your API has a subscription
-
36:08
service for the stream of activity, and that's super awesome.
-
36:12
And maybe that's so awesome that you'll get
-
36:14
people to move from version one to version three.
-
36:16
But you can't count on it.
-
36:19
You can get deprecate APIs, Google does it.
-
36:22
You can deprecate old versions of APIs, but you will get pushed back.
-
36:28
So you, you need to, this is one of
-
36:30
the reasons of measuring APIs, this is really important.
-
36:33
You need to see which of your customers is is, is still on the first version.
-
36:39
So Ken Lang, the API evangelist, worked with a company who had different versions.
-
36:46
They had like four versions.
-
36:47
And only one customer was using the first version.
-
36:50
And he's like well, We can shut down the first version, right?
-
36:52
And they were like, Why don't you see who that customer is.
-
36:55
And that customer was bringing in $600,000 a month.
-
37:00
Okay?
-
37:00
That, that makes it worthwhile to keep that API around.
-
37:05
So it's not an easy thing you wanna try to prevent backwards incompatible changes.
-
37:14
If you introduce those, you're gonna need
-
37:16
to, to default, change the default more carefully.
-
37:22
Adding things is usually fine.
-
37:25
Removing or changing existing things is difficult.
-
37:28
So that's kinda the versioning thing.
-
37:31
You had a question?
-
37:33
>> When would you classify an API as failed on.
-
37:37
[INAUDIBLE].
-
37:43
>> It depends on the API.
-
37:45
If you give a very complex search query, that can take a while.
-
37:51
You do want to communicate in SLA to your developer.
-
37:55
The developer partners that you have.
-
37:57
And tell them what they can expect.
-
38:01
you, it is your job to try to make it as efficient as possible,
-
38:06
but you have, there's a lot of factors that you can't control.
-
38:09
You can't control the mobile device, its, how big its connection is to the Internet.
-
38:16
You can't control.
-
38:18
You can't always control the back end resource sometimes they get bogged down.
-
38:23
As an API developer you're kinda working with some back guys
-
38:27
and sometimes that search is going to take a really long time.
-
38:32
You can cash what you can cash and that's useful,
-
38:36
but there always gonna be times where things take longer.
-
38:40
So communicate with your developers what you know.
-
38:43
And if they tell you something's a problem, try to make it better.
-
38:48
[LAUGH] That's, I mean, that's, that's really.
-
38:50
Or just tell them that you can't.
-
38:52
Be honest with your developers.
-
38:54
Tell them the truth.
-
38:57
That's one of the problems I've had in the past, was when I wasn't
-
39:00
able to give developers honest answers about why things were the way they were.
-
39:05
And I think developers are grownups.
-
39:07
And we should tell them, hey that, that's there's a business
-
39:12
reason for that, and we have to do it this way, sorry.
-
39:15
Any other questions?
-
39:16
No, yes, Adam.
-
39:22
>> So you're anti-SDK, but what if your develops are pro-SDK?
-
39:28
>> Then they can write one.
-
39:30
[LAUGH].
-
39:32
>> Okay.
-
39:33
>> I mean, I, I, I think their parties at the libraries are great.
-
39:37
But I don't want to own it.
-
39:40
I, if someone makes a great API, a, a great SDK for my API.
-
39:43
And they support it consistently then I'll point to it from my developer portal.
-
39:49
If they make an A, an SDK for the API and they don't
-
39:52
keep it updated and they don't support people who ask questions, I won't.
-
39:57
I'll just tell them to use the API directly.
-
40:02
I always encourage contributions from community members.
-
40:05
I love it when people make great third party libraries and
-
40:08
they usually will, but you have to have a standard, a bar.
-
40:15
For, for something's that it, it, if something is causing you more support
-
40:19
problems, then cuz the user doesn't think about it as a third party thing.
-
40:24
So if it's causing you more support problems than, than
-
40:27
helping people, let people find it on their own [LAUGH].
-
40:32
And, and just help the, you know, have them sniff the HTTP traffic
-
40:36
and see what's actually happening, so that you can help them debug the problem.
-
40:41
Yes?
-
40:42
>> For someone just diving into API development for the first time.
-
40:46
Do you have any specific resources that
-
40:48
you recommend for somebody just getting started?
-
40:51
>> Oh, that's great.
-
40:51
I didn't even throw her, she like, threw me a soft ball.
-
40:55
Okay there is a site, apicodex.3scale.net.
-
41:00
It is a site that I put together when I worked at 3scale.
-
41:04
The goal of that site is to actually give you answers to questions about APIs.
-
41:11
High level design they are written by some of the,
-
41:16
the smartest people I know who think a lot about APIs.
-
41:19
Mike Emson has a lot to say about hypermedia.
-
41:22
he, he is very eloquent.
-
41:24
Kim Lane, API Evangelists, thinks about a lot of things.
-
41:28
So that's a good place to go.
-
41:32
and, and if you don't find what you're looking for
-
41:35
there, pay attention to the people who are doing the writing.
-
41:38
That I thought were good enough to put in the API
-
41:40
codecs cuz it might have written something about what you're looking for.
-
41:44
Understanding who those au, authors are that are leading the
-
41:50
API maturity, will help you to, to find what you need.
-
41:56
And you can also tweet me, or send me an email.
-
41:59
Oh, so contact information for me.
-
42:02
As I said, I will post this on Slide Share with, with speaker notes.
-
42:06
Links to the things that I talked about that I remember.
-
42:10
You can tweet me.
-
42:11
@senedra.
-
42:13
You can send me email at senedra@gmail.com.
-
42:16
And I am princesspolymath.com.
-
42:20
So, you can go there.
-
42:22
I'm actually gonna put up a worksheet.
-
42:26
A cheat sheet of the things I talked about at
-
42:28
my workshop yesterday and the things I've talked about today.
-
42:31
So you could just download it, or click on the links and go visit the places.
-
42:37
I will be at the meet the speakers event,
-
42:41
with my drone that I used for my workshop yesterday.
-
42:43
So you can come play with the drone.
-
42:45
Trying to suck away all the users from the other speakers cuz I like to be cool.
-
42:50
Plus, it's my drone, [LAUGH] so.
-
42:53
anyways, so that's all the questions I'll take.
-
42:57
But please do find me.
-
42:59
Contact me, over the internet.
-
43:01
Find me here.
-
43:03
And have a great rest of the conference.
-
43:05
Thank you.
-
43:05
>> [SOUND]
You need to sign up for Treehouse in order to download course files.
Sign up