So as he mentioned, I am Kirsten Hunter.

I've been working with REST APIs for almost ten years now.

I started working with them in 2005 and

I've learned a lot about how, how to make APIs that developers love.

I always say that I wander the world like Caine in Kung Fu

teaching companies how to make APIs that develop don't make developers cry and

teaching developers to use APIs without crying.

So you'll see that I sort of design, it was designing irresistible APIs.

I had a talk with my publisher yesterday.

I'm, I'm writing a book about this stuff.

And they're like well but you talk about design in it so

maybe creating,and then they're oh no, just go with irresistible APIs.

So, this is about irresistible APIs.

There won't be any code, but I will give you a lot of, it should be interesting for

developers all the way up to executives.

People who want to understand how to have a good strategy for your APIs so

that it's, they're compelling, engaging, and fun.

So that was the intro.

Presentation style it says I promise notes on slideshare it always says that but

this particular topic I have on my blog princesspolymath.com.

There is a blog post at the very top that is about this, and

there's a webcast that I did for Oscon.

There's a link to the slide show,

and then there's a blog post that sort of sums it up.

So, the fact that I have these slides with just a couple words on them is for

a very specific reason.

Which is that I like to interact with the audience and

I like to pay attention to you.

If I have slides with bullets on them, then I'll read them to you and

you'll read them to you.

Everybody falls asleep.

Story time.

So this is, this is designed to be a conversation and not a lecture.

So, if you guys have questions, shout them out.

Ask me.

I love listening to myself talk and

I will talk for 45 minutes if you guys want to listen to me.

But please ask me questions if you have them.

I've been doing this a really long time so I probably have

some perspective on whatever, whatever it is you're curious about.

So love your API.

This is, this is the main focus of what I'm talking about here.

You're gonna make your API a first class product.

A lot of people don't make their API a first class product.

They let it grow organically, and I'll talk about that in a second.

But, basically you need to treat it like a real product.

You need to plan it.

You need to design it.

You need to develop it.

Put the resources on it, and support your developers so

that they have a great experience.

Organically grown APIs.

This is my favorite sort of way to describe them.

They're like, you have your product which is a potato and

you leave it in the garage for 30 days, and then all of a sudden it has all these

little sprouts and they're ugly, and not related to each other.

And nobody likes them and

they're, and, and, and they don't really work out for anything.

That's what happens when you, people just sorta try to slap an APON,

API on an existing backend without having an overall strategy.

You end up with inconsistent interfaces, something that happens on your

product on the main website works totally differently in the API.

You have duplicate code, which is, is kinda stinky.

It it means that when you have a bug in one place, you have a bu,

you have a different bug in the other place.

You never wanna have duplicate code.

You'll notice that the duplicate code is not exactly the same.

That's how it works.

Do you have a question?

You just wave [INAUDIBLE].

>> [INAUDIBLE]. [INAUDIBLE]

>> Resource contention.

One of these things that people seem to think when we have these

organically grown APIs is that we're gonna make a new feature on the main product.

And then in their spare time,

the developers are going to also make an API and it's gonna be great.

Well, developers already have to develop the code.

They have to do something with documentation,

which they don't really like.

They have to do stuff with tests, which a very few of them actually like.

And now you're saying you also have to make an API.

If you don't set aside actual resources for this, it's not gonna happen.

You're gonna end up with a serious mismatch.

And you're gonna end up with feature mismatch.

So this is the ugly pants API but you will see that they're not the same ugly pants,

they're different from each other.

What does make an API great?

How, how do you create an API that everybody talks about and loves?

And also I want to make a side point here.

Some of you are gonna have internal only APIs.

You're in an enterprise and your customers are internal.

And you're gonna argue to me no, actually, I don't have to care about my developers,

the developer experience is not important to me.

Let me just tell you is it more important to you if people have to use your API and

it hard to use, and it's not clear how you're suppose to use it.

You're end up with huge support cost and internal politics problems.

So you need to think of your developers as customers, what ever kind of API.

Whether it's open API's, which is mostly how I refer to these.

But even if it's internal, that's a really important thing to do.

So what makes an API great is basically a fantastic developer experience.

You want to make it so people want to use your API, that they enjoy using your API,

and they get, and they use it in a way that you expect them to.

And how do you do that?

With deliberate design.

Instead of having your organically grown potato.

You know, you,

you couldn't make origami if you didn't know what you were doing at the beginning.

Right? You would end up with,

well, a flapping bird or you know, a wingless swan or something.

It doesn't work.

And so we're gonna talk about the process of going through and

creating your API just like any other product.

And now I'm gonna digress again, cuz I do that, and talk about API first.

This is the Utopian ideal of the API world.

This is the world where instead of having your product run off of your back end and

your API run off of your back end separately.

You have your API run off of your back end and all of your products,

your mobile devices, your main website and everything, all runs off of that same API.

And when you open those up and let other people use them, they're the same API.

Now, we don't have code duplication.

We don't have feature mismatches.

Our interfaces are consistent.

And I have people telling me, no.

I can't do that cuz I'm a little start up and

we don't have time to put the framework in place.

It does improve your productivity and makes your iterations faster.

So, when you're starting out, it's still a great thing to think about,

especially if you're gonna have more than one product, and you probably are.

You're probably gonna have a web experience and

a mobile experience at least.

So, then I hear people saying oh no, we're, we're a really big company, and

we can't possibly refactor everything so that it, it's API first.

Like it's just not gonna happen.

So, I give you this picture is about Etsy.

Etsy is I think we can all agree that they're legit company.

They transacted over a billion dollars last year.

And they decided last year to go API first, and

they basically refactored their whole backend all at once.

And they discovered that an improved communication between their teams

it it made their iterations much faster.

It reduced the amount of bugs that they had.

It, it increase, increased their developer happiness because they,

they weren't having to do things in two different places, two different ways, or

come together.

And a few of the, the products that they have, a few of the features on their

website actually got significantly better, and were able to from asynchronous calls

that took several minutes, to synchronous calls that took less than a second.

So, I mean a part of that is because if you have a thing and you throw it away.

And then rebuild it after you've gone through and

figured out what your actual use case is.

It's gonna be better, but it is possible to do that.

Now, Akamai, the company that I work at is doing API first

in a slightly different way.

Again, we're a huge company and

we don't actually have the capability to refactor everything all at once.

So, we have a two year plan to try and

move everything, all of our products to an API backend.

Decouple everything and make it so that we can open up those APIs.

So, there's various ways to do this.

It's worth thinking about.

And even if you don't do it, at least you can think about what you're giving up.

What the cost is of not approaching things this way.

So the first thing you're gonna wanna think about in this planning of your,

of your API, creating an API that's irresistible is, why do you have an API?

So, imagine that you're stuck in an elevator with your CEO and

your CEO turns to you and says, why do we have an API.

Historically speaking the answer that developers like to give is because API.

Everyone should have one.

We should have one too.

And then your CEO takes all of your developers and

moves them over to a place that actually makes money, and you have no API.

So, you need a business, you need to know what the business value is of your API.

And even internal APIs, what are, what is it that you are trying to achieve?

So, I'll give you some ideas for

open things to give you an idea of how that works out.

Mobile or market penetration.

Let's all think about Netflix.

Okay. So, Netflix has an API.

It use to be open.

It's not so open any more, but they still use it for their devices.

And they had a strategy that basically went like this.

If there's a thing and

it makes pictures, and it makes video and it's connected to the internet.

It should have Netflix on it.

So, now you can't buy a Blu-ray player or any kind of smart TV or

anything that doesn't have Netflix on it.

We're starting to get more Hulu and Amazon Prime.

But Netflix is not a competitive advantage any more.

Not having Netflix is a competitive disadvantage.

No one's gonna buy your Blu-ray player if it doesn't have Netflix.

So, by having an API that was really easy to integrate with,

they made it a, an, aggressively going out and using that,

the simplicity of that integration to chase down the manufacturers.

They created this market penetration that,

that assures them of a certain amount of traffic well into the future.

Driving usage, Twitter's a great example.

So, when Twitter started they were, like this page, and

you could type in your 140 characters and you could follow people, and that was it.

If they hadn't had an API we wouldn't, we wouldn't use Twitter the way we do now.

We, we tweet from everywhere, we share things.

We integrate with a lot of other kinds of systems.

And as a result, the, the stream is much more rich.

People are able to integrate to integrate their applications with Twitter, and

so Twitter can have information coming in whether it's shared off of a news site or

whether you did something cool with your Fitbit.

Or whatever, whatever it is that you're gonna share.

So, the usage for Twitter, the thing that's really important for

Twitter is that people write to the stream.

If people don't write to the stream, its boring, and then people go away.

So, that's what they use their API for, it was to drive usage.

They did some not terribly popular things for the developer experience.

But in general, their API was successful in this goal.

Getting their first will help you to defend against interlopers.

Best Buy actually had one of the first API's in their, in their industry.

And it helped them to get a lot of traction and

integration with other people and other products.

So, Amazon was their first, and

they have consistently been their first for different kinds of features.

So the fact that their website is a little hard to use

doesn't mean that people don't buy things from them.

They are again the defacto standard.

And they are very committed to API's and making it possible for

people that integrate with them.

My favorite of all of the business values, and this is the one that your CEO

will really love, partners connectivity, partners stickiness.

So, if you have a partner and they've integrated with your API, and

they've updated your, integrated so that their reporting includes information from

your API as well as their back end systems.

And then six months from now,

somebody says, hey, we really wanna buy this other product.

The engineering manager's gonna push back, they're gonna say, I don't,

we wrote code, and it works.

So we don't wanna write more code.

So, it doesn't give you a free pass if you have a terrible developer experience or

bad support, people still might wander off.

But it does add some friction to that decision to make the change and

it gives you an opportunity to try to keep those partners.

Partner contracts are one of the most stable sources of income for

most companies.

And so being able to get your hooks in [LAUGH] is, is a really helpful way to get

people to play with your stuff and, and keep, keep using your main product.

And then there's a few technical cases,

making things that are super hard, super easy.

this, this is usually the case when you are talking about a company that,

where their API is their main product.

So, SendGrid and Twilio, and Contacts.io.

So these people SendGrid makes it easy to send in and,

and deal with email from the sending side.

Contacts.io makes it easy to deal with email on your side.

It can make it so that you can have really complicated rules,

you can actually use your email as almost kind of a database.

Dealing with emails pretty tough on a programmatic basis.

So it's really nice to have these APIs that will deal with this for you.

Tullio, so who of you have written telephony clients before?

[LAUGH] It's hard.

Sending us a messages doing voice conferences.

all, transcription, all of the things that Twilio does.

It's not magic because they have a great developer experience, although they do.

It's magic because these are things that you, you just wouldn't add SMS

integration into your application if there weren't an easy way to do it.

It's, it's not most people it's not their core competency, and

it is very, very difficult.

So now we've got our business value.

We know what it is that we want to do with our API.

How do we measure success?

So I've worked at companies where the metric that we use is how

many people have an API key?

Okay.

That's, that's probably not interesting at all to your CEO when you're standing in

the elevator,.

Something more interesting might be how many people are using the API

versus how many people are using the main product.

It's a lot cheaper for you if people use the API.

Your sending a lot less information across the stream, and

their doing sort of the client end.

Whoever the, that application is.

Maybe it's, you know, are your partners using it consistently?

Is that helping?

Whatever your business value is,

figure out how you want to measure it, what chart or graphs you're gonna show,

and also this will help you chase down what your use cases should be.

Use cases are critically important in

terms of figuring out how you're gonna design you API.

I'm gonna talk about some other architectural considerations.

But the use cases are gonna be in my opinion,

your main product should, should essentially be an API use case.

Mobile should be an API use case.

integration, if you want to have integration with social systems,

then maybe that should be a use case as well.

So, once you've fitted, figured out your business value and

how you're gonna measure it.

It should be a lot easier to come up with use cases.

How do you want people to use your API?

Which things should be easy?

So, architectural considerations.

I am going to talk a little bit about mobile as a,

as a target, to give you an example of what it is that you are thinking about.

So if you want people to use your API for

mobile devices then you have to realize some things.

First of all they don't like getting a lot of extra data.

They, they wanna get exactly the data that they want and they wanna get it fast.

Second of all, they want one copper screen.

So you need to be very careful when you make those mobile use cases that

you figure out a way to make it possible for

them to do one call per screen as opposed to making 50 calls.

Those of you the people who use phones they walk into into elevators,

they go under tunnels especially around here and, and the connectivity goes down.

So, you retry one call that's not so bad.

You recall 50 calls that's kind of a pain.

And also most phones don't thread too well and

you end up with a nonperformant application.

So people wander off and use somebody else's API.

One of the ways you can give somebody what they need,

exactly what they need is to have an expressive query language.

So, Netflix has a pretty basic expressive query langauge because their,

their content is, is a pretty simple graph.

There's movies and there's people and there's genres.

And other than that, there's not a lot of stuff.

So what they made it possible to do is,

as a device, you want to pull all the information about this movie.

But you'd also like to get some information about the cast,

and maybe pictures of the actors, and information about the director, so

that you can create a really excellent experience on your device.

So the, what Netflix allows you to do is just expand those queries.

So you can say I want this movie and expand the cast,

the director, and the genre information.

And then you know,

the device can use that information, it doesn't have to make a lot of calls.

In this case, the Buse case devices.

If they're going.

If you're going to be watching a streaming movie from Netflix you probably have

a pretty fat pipe.

So, it's not necessary to consolidate that down and make peep,

make it possible for people to get less information and very targeted information.

LinkedIn on the other hand has a very complicated graph.

There's people and they have connections and there's schools and there's

businesses and there's organizations and there's all of these different things.

And they want to make it possible especially for mobile devices, but

any device to be able to say I wanna know all my connections what,

what state their, their their school was in and

what company they worked for and how long they've worked there.

But I don't want other information, I just want those things.

So, Netflix, LinkedIn made it possible to express that kind of,

of level of, of specificity.

The problem is that that makes it more complicated for users.

But for the developers, it is a little bit harder of a developer experience.

But on the other hand, once they get exactly what they want,

they can continue to give exactly what they want.

And, and LIncoln kind of encourages people to do this.

The default object for most things is very, very simple.

So they want you to express exactly which fields that you want, and

which ones you want to be expanded out.

Another one of the architectural considerations you're gonna have

is hypermedia.

Do you have stuff that's, that's very closely linked to other stuff?

Netflix does in fact use hypermedia.

So, one of the ways you can figure out what you can expand in their API,

if your device is through the meta links that they have,

that show what the related items are.

So, there's a movie, and

one of the related items is the cast for that movie, for instance.

So, hypermedia is a fantastic thing.

One of the nice things about hypermedia is you,

this is one of the decisions that you can kinda put off until later.

If you add metadata to an existing API, it's not gonna break anybody.

So, when your people start, your developers start coming to you and

saying, I wanna be able to discover more information about the items that I

am looking at could you please make it easier for me to do that.

Then, hypermedia is a great idea.

But you don't have to have it right up front, it's just,

it's something that you should consider.

You should read a little bit about hypermedia,

figure out if it's something that will make your API more compelling for

users, if that's how you want to make it easier for people to do things.

One of the things that happened when we went from SOAP to REST is that a lot of

enterprise people got really upset, because they, they thought,

oh now everyone can see everything and we can't control it anymore.

That's not really true.

Just with any,

as with any other system you can control who sees what and who can do what.

I try to remind everybody that,that authentication is

different from authorization.

So I have a driver's license.

It says who I am.

That's my, that, that's, I have now authenticated it.

You know who I am.

But that doesn't necessarily mean I can vote.

It doesn't necessarily mean I can buy beer.

It doesn't necessarily mean I can be the president yet.

So keep in mind that sometimes you're gonna have user that have specific eh,

a specific read-only or very, very closed access.

And sometimes you can have administrators that can do pretty much any,

anything that they want to do.

So you've got your use cases,

you've got your business value, how you're gonna use it, you've got your use cases.

Now how are you gonna describe your API?

One of the big problems with API's is that the developers figure out how

they're gonna make the API but they don't have a really good way to describe this to

product managers or other people who might want to know how the API is going to work.

Schema modeling is an excellent way to describe how the API is gonna work.

Apiary has a, a, a, uses Blueprint.

Ulsoft has Ramel Reverb has swaggered their,

a bunch of different ways to, to represent this information.

But what's really important about it is it describes how your API is going to behave.

If you use someone like Apiary you can actually create a mock server.

People will be able to take their clients and throw it against that and

see if it's gonna have the, the depth of information they're looking for.

This is a valuable, valuable step that frequently gets skipped.

And this allows to ensure that consistency across your APIs.

I've seen cases where the user that shows up under account is totally different from

the user that shows up under ownership of pages.

You don't wanna do that to your developers.

You wanna make sure that a user is a user, is a user wherever they run into it.

And one of the things that will be helpful with that is if you model your schema,

you can look at it and

see where those inconsistencies are before you start developing.

And I'm sure you're all familiar with the, the notion of test-driven development that

we all rambled about for several years while we were doing Agile development.

So I'm advocating for design driven development.

So we're not making a test that fails and then writing code so that it succeeds.

I mean that's super fun, it's a great game,

and, and it, it's good until you are super busy.

Design driven development says what we're,

what we're coding against is that design that we've created.

We're making sure that that is true.

We're making sure that we're sending back exactly what we said we

were gonna send back.

It's whatever version of schema modeling you use.

It is a blueprint.

It describes how your API is gonna work.

And if you develop against it, you're gonna have a lot fewer iterations.

You're gonna have a lot fewer situations where developers are going to

have to re-do work.

Which is very frustrating.

And your iterations will be faster.

And you'll get to those used cases a lot faster if you know how it

is that you expect to get to them.

So I'm gonna give you guys a little story about,

about when I gave a workshop in Europe.

So I was in London at the Future of Web Apps.

A few weeks ago.

And I gave a workshop where I had people do a really complicated thing.

Which was, you know, create a mock API and then put it on the Google cloud and

look at it in Rumscope and, and de, deploy it to the cloud.

And then they all just sat there and looked at me.

And I was like, do you have a question?

Was it fun?

Is it excite, you know, and then, and finally,

one of them sort of looked at me and

said, I'm resting on my laurels because I just applied something to the cloud.

And I was like oh, that's your ecstatic phase.

So, I like Americans cuz Americans, they, they know they have the happy face.

They have the confused face, they have the bored face.

I can figure out whether I need to speed up,

slow down expand on something, slow things down.

But whatever it is that the ecstatic face looks like for your developer, so

this is an ecstatic London developer right here.

Whatever that ecstatic face is,

that's the face you want them to be making when they think about and use your API.

The first thing you wanna do is think about how to communicate with them.

Now you know your business value you have.

You're gonna measure it.

Your use cases, you have a design.

You're developing based on the design.

I would argue that you need to tell your developers all of those things.

Why?

Because many times in the past, people have not communicated what their

goals are for the API, and then the API's been pulled out from under the developers.

Developers are gun shy.

They might not want to use your API if they aren't sure it's

gonna be there in a year.

They're trying to monetize or they're trying to make a product.

And then need to under, believe that you have a solid foundation.

Is, if you show them, hey, I thought through this stuff.

I actually have a plan for this API, and this is how I'm gonna measure it.

They'll help you, they want your API to succeed.

So that if you say what I want is write to the,

to the stream, they'll think about how to do that.

How do I write to the stream?

So, treat your developers as valued partners,

not as annoying kids on your lawn.

I, I, I've found people who do both, and generally,

developers will react in exactly the way that you, you interact with them.

These people are giving you the most valuable thing they have, their time.

They're never gonna get any more of it.

So, if you show that you respect that, then they will trust you.

And they will start using your API.

Again, internal API's, still important for people to understand the goals of the API,

what you want them to do with it, how you want them to do that.

Marketing to developers is not like marketing to regular people.

This always gets re-tweeted as not like marketing to real people which, you know,

I can own that, but

really it's regular people like pictures of pretty things and developers like toys.

They like examples.

They want to know why do I care about your API?

What can I do with your API and how would I do that?

unfortunately, we are generally very good at documentation that

says what does this call do.

But if the person doesn't have the context and

understand why that's important to them, it's not really meaningful.

Twilio has a very strong belief that a developer who comes to their site

should be able to make a, an actual call against their API within five minutes.

Akamai, not so much.

We have very complicated authentication systems, so

we try to get people to make their first call in 20 minutes.

[LAUGH].

But have a target.

Try to make it really easy for people to make that first call.

Make it clear to them that it is important to you that they engage with the API.

Once they've made that call, you kind of have your hooks in them.

They are kind of now invested in your API,

and they're gonna look around some more and see what else they can do.

Example Code: these are toys.

I actually have started making something I call "The Island of Broken Toys" where I

have a working, script and then I have one that's kind of broken in four or

five different ways so that people can debug and figure out how the system works.

Make it really fun for people to play with your example code.

It should be really easy for people to use things.

Encourage your community to add more examples.

The more ways that people can interact without actually starting from scratch,

the more likely it is they'll stick with you.

And give them tools, tools such as

console Apple G has a console IO Docs is what Mashery uses.

Make it possible for

people to explore your API without having to make those calls.

So if what they wanna do is go look around and

kind of see what the various things are.

This is especially useful for someone who has already made that first call and

now they're trying to figure out what it is that they wanna do and

what they wanna build.

Encourage them to use things like HTTP sniffers or

RunScope, to understand what that traffic looks like.

Help them to be successful.

Assume that they're gonna have a problem at three o'clock in morning cuz

they're hacking on your API and that's when they were awake.

And they, they get frustrated, and they come, and they ask a question.

Well, you're not there until you know, we're developers, so ten or

11 in the morning, and that's a long time for someone to wait who's frustrated.

So, try to get ahead of it, and teach them how to do what they

want to do with your API without needing your direct help.

But do you give him them that direct help when they need it?

Tell them what your SLA is.

Are you gonna respond to the requests on the forum tomorrow morning?

Are you gonna respond to emails in four hours?

It's what ever you choose is fine, but

you need to make sure that your developers understand what that, what that SLA is.

Understand what they can expect from you.

Otherwise they get frustrated.

They're already frustrated cuz they're asking questions.

So you wanna make it,

it clear to them what they can expect to happen when they ask for help.

Okay, so.

All intelligent discourse on the Internet ends as soon as someone p,

posts a picture of a cat.

So here's my picture of a cat.

And now I'm gonna, I'm gonna encourage you to ask questions.

If you don't ask questions, then I'm gonna ask myself questions and

we don't really want that.

So remember that I've been an API evangelist for ten years, so think about

any questions you may have around APIs, around creating them or designing them or

supporting people and or, you know, ask myself questions.

>> So as I like to do let's make sure that we give Kirsten a round of applause first.

[APPLAUSE]