00:00:16.480
um hey everyone my name is john and uh we're going to talk today about designing great apis
00:00:24.080
as a little bit of background i work for a company called brightcove breycov does in video publishing for big media
00:00:30.800
companies enterprises and small businesses and startups and all sorts of companies i came to brightcove via a
00:00:36.399
company called zencoder which breikov acquired last summer and zencoder is an api based product for
00:00:43.680
video and audio transcoding in the cloud so it's basically high scale high performance video and audio transcoding
00:00:49.520
so i've been working on apis for the last like three and a half years that's been my entire focus our
00:00:55.039
product was an api um so today when i talk about api design i'm going to use some
00:01:00.079
examples from the life of zen coder talk about my experience with this but of course i want to talk about
00:01:05.439
other apis as well and general principles too
00:01:10.560
so um hopefully everyone here knows what api stands for if you don't this probably is
00:01:16.720
not going to be the right talk for you um who here has worked on an api before raise your hand
00:01:22.479
all right that's like everyone that's great who's worked on an internal kind of service-oriented architecture internal api what about an external
00:01:28.960
productized api so good good mix everything we talk about i think will be
00:01:35.119
equally applicable to both and maybe we can kind of discuss differences between those approaches
00:01:41.360
if we have time as well as you all know the i in api stands for
00:01:47.280
interface and an api is an interface we think a lot about this as an
00:01:53.200
interface is maybe a user interface uh if it was the 80s we'd probably call it a graphical user interface now it's just
00:01:58.320
a user interface um but this is an interface as well
00:02:04.479
who who is the user of this interface developers
00:02:10.319
any any other users machines software
00:02:16.560
i think every api actually has two users and they both have different concerns so there's software
00:02:21.760
and a programmer what does the software user want what does the machine user want in an api
00:02:32.480
data consistency
00:02:42.640
ultimately it comes down to uh to um working and working the way that the machine expects so syntax correctness
00:02:51.120
efficiency speed scale all those things are important to the machine user of an api
00:02:57.840
what does the developer user want in an api ease of use what else
00:03:04.800
simplicity clarity understandable documentation yep
00:03:10.400
ultimately what what we want as developers when we interact with an api is we want our apis to actually be
00:03:16.000
designed we want to recognize that this is an interface to us and and it's
00:03:21.440
important to think about the developer user of an api when creating an api
00:03:26.640
just as a user interface for a maybe a website can help make a website easy to use help people
00:03:33.040
accomplish their goals make it easy to understand make it pleasant to use the exact same things can be done with a
00:03:39.440
good api design so that's what we're going to talk about today we're going to talk about it through
00:03:45.440
three lenses the first is george orwell the second is
00:03:50.879
a guy named dieter rahms and the third is something called the kano model
00:03:56.000
orwell is going to talk about writing and we're going to see how that kind of relates to apis dieter roms
00:04:02.640
talks about industrial design and the kano model is a model of product development
00:04:08.560
along the way uh we're going to i'm going to pull out kind of five guiding principles that i think should guide every well-done api
00:04:14.720
we'll look at some specific examples and tips of maybe good and bad api
00:04:21.199
api structures and hopefully i have some time for a discussion too i've been working on apis for about
00:04:27.120
three years and that's probably a tiny slice of like all the time in this room that has been uh spent working on apis
00:04:32.960
so hopefully we can talk a little uh so
00:04:38.800
we're gonna start with george orwell is best known as a novelist he wrote novels like 1984 an animal farm that
00:04:45.680
many of us i'm sure have read but he's also an essayist and he wrote what i think is one of the best essays
00:04:51.360
ever written on the topic of writing it's called politics in the english language
00:04:56.639
um why are we talking about writing quick quick answer is programming has a
00:05:01.680
lot in common with writing programming is actually a form of writing when you think about it programmers take abstract ideas and make
00:05:08.240
them concrete in a particular language it's the exact same thing that a writer does um and so ruby gives us a grammar ruby
00:05:15.199
gives us a language in which we can write our ideas create our processes uh create the work that we want our
00:05:20.639
software to do um what does an api view i i would argue that an api extends our
00:05:26.800
language it gives us new nouns and new verbs to be able to write things that are maybe more powerful
00:05:33.120
than we could do without uh so in in uh orwell's essay um he
00:05:39.919
gives some examples of good writing and bad writing uh gives some tips that we'll look at for writing with good style but he also does something really
00:05:46.479
interesting he connects good writing to good thinking and it connects bad writing to bad
00:05:53.600
thinking and so it says that that's actually a key tool of political oppression and totalitarianism
00:06:01.280
um as an example um of the sort of political writing and political speech
00:06:08.080
usa patriot act what was this act about
00:06:14.560
9 11 9 11 not usa patriotism
00:06:20.080
this this act this this legislation was specifically given a name for the purpose of obscuring thought um you you can't
00:06:27.759
you can't have a rational discussion about the pros and cons of usa patriotism if you're a united states senator
00:06:34.000
instead this this this label was uh this name was created to shut down discussion so this is bad writing
00:06:40.400
that creates bad thinking a better name for this would have been something like maybe the expanded surveillance act
00:06:45.840
something neutral and direct that we could have a we could have a discussion about we could say reasonable people could discuss should we expand
00:06:52.160
surveillance in the wake of 9 11 or should we not but a name like usa patriot act is
00:06:57.360
written intentionally to prevent that that's why orwell says that bad writing
00:07:02.560
is a key tool propaganda um here's an example he uses in the essay um imagine this in the being
00:07:09.120
written by a left a leftist professor in england in the 40s or 50s
00:07:17.599
while freely conceding that the soviet regime exhibits certain features which the humanitarian may be inclined to
00:07:23.120
deplore we must i think agree that a certain curtailment of the right to political opposition is an unavoidable concomitant
00:07:29.840
of transitional periods and that the rigors to which the russian people have been called upon to undergo have been
00:07:34.960
amply justified in the sphere of concrete achievement what is this actually saying
00:07:42.639
that's right this this this is saying that purges and gulags and political oppression are acceptable but you would
00:07:48.160
never come out and actually say that instead you hide that kind of position in this sort of bad writing uh that
00:07:53.680
keeps people from thinking clearly and deeply and rationally about what you're saying
00:07:58.960
here's a much less sinister example taken from some academic literature
00:08:05.840
i'm not indeed sure whether it is not true to say that the milton who once seemed not unlike a 17th century shelley
00:08:11.360
had not become out of an experience ever more bitter in each year more alien to the founder of that jesuit sect which
00:08:17.360
nothing could induce him to tolerate what's that saying
00:08:23.520
anyone interestingly enough besides being totally incomprehensible the um the
00:08:29.280
fourth knot should not be there uh and the word alien should probably be akin um so this is actually too difficult for
00:08:35.919
even the author to think like coherently about what they're writing
00:08:40.959
so orwell gives six principles for writing with good style and here they are he says
00:08:47.200
never use a metaphor simile or other figure of speech which you are used to seeing in print
00:08:53.200
second never use a long word where a short one will do third if it's possible to cut a word out
00:08:59.680
always cut it out fourth never use the passive where you can use the active
00:09:07.120
fifth never use a foreign phrase a scientific word or a jargon word if you can think of an everyday english
00:09:12.640
equivalent sixth break any of these rules sooner than say anything outright barbarous
00:09:20.720
these are interesting rules to think about in terms of how we write in terms of how we program uh but also how we
00:09:26.240
design products and how we design uh things like apis i i get a couple principles from this um the first is
00:09:32.560
that a good api is minimal um we as uh software
00:09:38.320
developers work with massive complexity uh we're dealing with uh maybe thousands or tens or hundreds of thousands of
00:09:44.000
lines of code functionality that we can't keep in our heads uh you even come close to keeping our heads and the best
00:09:50.880
way to be able to deal with that problem is to think clear is to write code write
00:09:56.640
software and create products that are simple and minimal and clear for example in the zencoder api there's
00:10:02.880
about 150 parameters you can pass uh advanced settings for choosing your format your video format your resolution
00:10:09.680
your bitrate all sorts of little micro knobs that like maybe no one ever has to do or maybe only a couple customers ever
00:10:15.360
have to use but you can send us a single parameter and
00:10:20.560
we will transcode a video to probably about what you want so it a little it's
00:10:26.560
uh uh basically it chooses smart defaults it does smart things with the attributes
00:10:31.680
that you don't tell us we'll make smart decisions about resolution and bitrate and all that
00:10:37.920
so all that complexity is there under the surface and it's fine to have that if you need it but keep the default case as simple as
00:10:44.079
possible and then people can layer on the additional complexity that they need
00:10:50.800
second principle a good api will get out of the way
00:10:56.000
so just as good language and good writing it doesn't call attention to itself it doesn't obscure it doesn't
00:11:02.000
obviously what it's trying to do good i think a good api design is direct
00:11:07.839
and you almost don't notice it for example use rest if you see an api
00:11:16.240
today that uses something other than rest that's probably the first thing you're going to notice and you're going to say
00:11:21.360
why are they using soap or why are they using whatever it is and consistency is a really important
00:11:27.040
principle uh here as well uh if you're going to if you're going to uh return a certain kind of response in one situation always
00:11:34.000
return that response in any situation similar structure your json or xml in a similar
00:11:39.440
way so that you don't create a consistency um just a little example
00:11:45.200
um http gives us two codes um for for uh authorization authentication um i've
00:11:53.040
seen applications that will kind of mix these they'll use them inconsistently in different places there actually is a good reason for
00:11:58.800
there being two of these but it's kind of it's not something that
00:12:04.399
we should have to worry about any thoughts or questions on
00:12:11.120
any of this so far
00:12:16.880
um great let's uh move on so uh we're gonna talk now about a guy named dieter rahms
00:12:23.440
um deuteronomy was the chief design officer at braun for a long time and he's one of
00:12:28.560
the most famous industrial designers ever he's incredibly influential he's very influential on a guy named
00:12:33.920
jonathan ive who we all know as the head of design at apple who today is the company we all
00:12:39.760
think of when we think of industrial design but 30 years ago was brawn
00:12:46.000
jonathan ive has a took a lot of inspiration directly from drams and i'm going to read a little uh
00:12:56.480
read a quick paragraph from an introduction he wrote to a book on roms
00:13:01.519
ive says when i was a young boy growing up in london my parents bought a wonderful juicer it was a brawn mpz-2 citromatic h
00:13:10.320
i knew nothing about dieter roms or his 10 principles of good design but to a little boy uninterested in juicing i
00:13:16.320
remember the citromatic he and his team designed with shocking clarity it was white it felt cold and heavy the
00:13:23.040
surfaces were without apology bold pure perfectly proportioned coherent and
00:13:28.320
effortless um and see if you can create a picture of
00:13:33.440
anything here it was clearly made from the best materials not the cheapest at a glance
00:13:38.480
he knew exactly what it was and how to use it it was the essence of juicing made material a static object that
00:13:45.200
perfectly described the process by which it worked it felt complete and it felt right
00:13:51.920
so imagine for a second if apple were to create a juicer which i don't expect they will but if they
00:13:57.680
were what would it look like maybe something like that
00:14:06.000
you can see the influence that ddram's had on apple's designs here's a few other examples
00:14:16.000
on the left we have a braun product and on the right we have an apple product
00:14:22.959
so i'm going to let ddrams
00:14:28.320
quickly go through the ten principles here see if ah this works design can everyone see the subtitles
00:14:34.959
this is in german subtitles yes no google's design is
00:14:42.199
aestheticist design buddhist design products
00:14:49.360
design is early buddhist designers
00:14:55.279
this design is langley
00:15:08.639
last but not least
00:15:17.839
so we're going to talk through some of these uh principles of industrial design and how they relate to
00:15:24.480
our jobs building apis um first uh good design makes a product
00:15:30.560
useful um i think sometimes we think about design as being something super superfluous right it's like additional
00:15:36.560
style added to something maybe you can take it or leave it throw a little color on it that's the design
00:15:41.680
but that's not really true anything ever created by a human is designed
00:15:47.040
um it's just that there's good design intentional design and maybe bad design and good design helps make things
00:15:52.079
functional it helps empower the people who are trying to use it it helps make maybe every aspect of how something
00:15:58.000
could be used make it possible i think extending this a little a key
00:16:03.680
principle of design and industrial design is that you want to design for the extremes you
00:16:09.360
don't just design for the average case how the average user might use something we actually design for the the the edge
00:16:14.720
cases here and here and if you do that the middle will probably take care of itself
00:16:20.079
so for example if you're thinking about api design uh let's let's say you're building an api to like uh like a phone system like
00:16:26.880
twilio or something like that um think about that product and that api
00:16:32.320
think of how a power user like an expert user would use that uh that api um someone who actually has built telephony
00:16:38.720
systems internally how do they encounter your product or um
00:16:44.399
many of us here probably deploy to linux and are linux users or mac users how would a window use windows user
00:16:50.480
encounter your api it shouldn't matter right an api should be totally uh um agnostic to with the language or the
00:16:57.199
platform that's accessing it or think about how like the wrong customer would use your api someone who
00:17:03.839
shouldn't be using it they're not your target market they probably don't even maybe they probably don't know how to do it um
00:17:09.199
how do they encounter it so like at zencoder we um we are an api only product and that's
00:17:14.880
intentional we never stood up a web page where you could upload a video get it transcoded and download it um and the
00:17:21.039
reason is we didn't want like you know 10 000 people doing one-off transcoding on our
00:17:26.240
platform that would be a support headache it wasn't our it wasn't the product that we were trying to design and actually making that decision not to
00:17:32.880
not to even allow that helped segment users so the only users who could use our product were
00:17:38.400
programmers in terms of extremes think about scale
00:17:43.919
think about how will a user use your api at not not normal usage but huge usage
00:17:49.360
either intentionally because they're big or accidentally because they they they write an infinite loop that
00:17:54.799
keeps uh exercising your api over and over which has happened to us quite a few times as encoder
00:18:00.960
um think about how a bad programmer would interact with your api
00:18:06.240
um someone who doesn't really know what they're doing but maybe thinks they do this is actually uh
00:18:13.280
this is actually um uh uh almost any time we have a an unhappy
00:18:20.240
customer or customer support issue as encoder it was because they were they didn't really know how to program but they thought they did
00:18:26.000
um so they would try it they would try what we're doing and they'd say it doesn't work it's horrible uh in fact it worked fine it was properly documented
00:18:32.160
but they didn't know what they were doing um so this is something that we've spent a lot of time trying to design our
00:18:37.280
system to be used by everyone um but it doesn't always work um here here's actually an email we got we we had a um
00:18:45.039
someone tried to use our system and didn't understand how we do url encoding which is kind of a you know
00:18:50.160
complex thing but we very clearly laid it out and told them how to do it and show them documentation and the guy just didn't believe that we
00:18:56.880
knew what we were doing and he sent us this email he said ben who's one of our customer support guys uh ben no ben i
00:19:03.679
went back over everything again and again and it still didn't work so forget it then please see that my credit card
00:19:09.120
is not charged then i have no interest in your services ben for this pw card he was integrating with
00:19:14.240
like premium web cart which maybe tells you something about
00:19:19.360
him um maybe later for something else but i doubt it then i find your service lazy and incomplete your support
00:19:25.760
arrogant and not very knowledgeable looking forward to never seeing your name and company in my inbox again
00:19:31.760
richard
00:19:41.200
yeah i left his last name off but you can actually find him on twitter so uh anyway
00:19:49.120
um so if you design for the power user and you design for this guy you will have
00:19:54.720
everyone in this room uh covered with with your product um next good design is aesthetic
00:20:02.080
this is what sometimes we think about is design design is making things beautiful and that is actually entirely true good
00:20:07.440
design should make products beautiful who knows what this is
00:20:13.760
what's that vb camelcase what else hungarian notation who thinks hungarian
00:20:20.240
notation is beautiful raise your hand
00:20:26.480
um we're all here today as users of ruby and ruby is a language that was designed
00:20:31.919
by mats in order to make developers happy and a big part of how ruby does that is actually being just a really
00:20:38.559
elegant language it's it's it's uh probably the most beautiful language uh at least i've ever encountered even
00:20:44.400
people who hate ruby usually give us that good design makes a product
00:20:50.320
understandable let's let's look at a kind of fake api
00:20:55.440
here let's say you have an api that someone sends this request to you they give you
00:21:00.720
an api key of does not exist what do you do
00:21:06.400
if you want to if you want your api to help the user understand what's going on well you could return like a 500
00:21:12.000
internal service error because you didn't handle the case of a fake incorrect api key
00:21:17.360
that's not very good so you can do better you can choose something like 401 unauthorized and say you know we were not able to
00:21:23.120
authenticate you because you didn't give us valid information but you can go further you could return
00:21:28.400
error message you could say api key not found at this point someone has a probably a pretty good idea why the request failed
00:21:34.799
but you could also provide some validation information api key may not include spaces
00:21:41.039
now they know not just that the api key is bad but they know something about why it's bad
00:21:46.240
finally why not do something like this api key not found please log into this url to retrieve your api key
00:21:55.360
here's another example um what's wrong with this request
00:22:02.400
missing a comma anyone ever been bit by that yeah um
00:22:07.840
you can return a 400 bad request this is a malformed request they sent this random bit of text and it wasn't json we
00:22:13.360
couldn't parse it um but why not go a step further and maybe include like
00:22:18.400
a lightweight json validator in your api so you can actually tell someone exactly
00:22:23.840
where what went wrong this this is this is the output taken from a sample parser i
00:22:29.120
think there's better ones today that actually give you a little more insight into like you know there should be a comma there but
00:22:34.960
this is easy to do next good design is honest
00:22:42.320
um a good api shouldn't leave ambiguity a good api should show clearly what's happening in a system should give full
00:22:48.640
insight into uh things when they're working when they're not working so for example if you send back a 200
00:22:55.360
okay make sure everything's okay never send this back with like an error message that says actually it didn't work
00:23:02.960
this is a perfectly valid thing to send back and everyone integrating with your api should handle this case if the service
00:23:09.200
is unavailable what do i do it's it's clear it's obvious uh it's honest and uh
00:23:14.480
you know the consumer of the api can maybe cue the request for resubmission what about this one
00:23:22.480
what do you do if you get a request timeout let's say let's say you're processing your credit card and you get a request timeout
00:23:29.440
you have no idea this this should never happen in a well-designed api
00:23:36.240
next good design is unobtrusive
00:23:41.760
um i'm going to show an example that's uh not at all related api design but i think it's actually i think it's kind of cool
00:23:50.240
it's really important in a product to have a sense of the hierarchy of what's important and what's not important by
00:23:55.919
removing those things that are all vying for your attention an indicator has a value when it's
00:24:02.240
indicating something but if it's not indicating something it shouldn't be there
00:24:09.360
i think it's kind of cool it's a it's a it's it's harder to do this sort of minimal unobtrusive design than to not
00:24:15.760
do it but it makes products better
00:24:21.440
good design is long-lasting who knows where i'm going with this
00:24:28.720
version your api when you first start an api product maybe maybe it's a startup and you don't
00:24:34.960
know uh how far it's gonna go or it's an internal project that you don't know if it's gonna be used
00:24:40.000
you don't actually have to do anything except scope just just name space that's all you have to do to version your api you don't have
00:24:45.840
to build a big versioning apparatus if you don't start this way you're going to encounter a lot of pain when you realize and you will realize if your api
00:24:52.720
keeps running that at some point you have to make a change that you can't just shoehorn in there's lots of ways to version an api
00:24:58.799
this is one of them i'm not going to get into issues there another one
00:25:04.960
this is simple but unique uuids make much better primary keys than
00:25:11.039
say like incrementing integers there's a lot you can do at scale if you are using guides as keys that it's
00:25:17.279
harder to do if you're relying on the senior database to give you back
00:25:22.559
ids for records finally good design is as little design
00:25:28.159
as possible kind of sums up dieter ramses philosophy and
00:25:33.840
also corresponds with orwell's thoughts so um we're not a fourth guiding principle
00:25:39.919
here good design is minimal it gets out of the way it designs for the extremes good apis are predictable
00:25:47.279
without even having seen an api you should be able to make a pretty reasonable guess as to how it would work
00:25:54.480
let's look at an example who here has integrated with the stripe api okay those of you who have be
00:26:02.000
be quiet for just a minute here those of you who have not used stripe before how do you think the stripe api works
00:26:09.360
what's the url that you hit if you want to make a transaction if you want if you want to charge someone money what are the parameters you have to do to
00:26:15.679
successfully charge someone something
00:26:22.880
here it is https that makes sense right credit card processing is probably secure
00:26:29.000
api.stripe.com that's pretty easy v1 slash charges
00:26:34.159
everyone here probably could have guessed pretty close to that maybe you wouldn't have gotten it but uh fortunately they have documentation you
00:26:39.760
should also you shouldn't make your users guess you should you should uh be predictable but don't make them yes
00:26:47.279
it requires a api key to uh to let stripe know who is charging money um
00:26:53.520
an amount a currency and then either a customer id or credit card information
00:26:59.279
that's it that's probably uh pretty close to what we would have guessed if we would have written it out
00:27:08.960
questions or thoughts at this point
00:27:21.600
yep the other question is what's what was the clip so both the clips i showed were from a movie called objectified
00:27:26.960
um has anyone seen it objectified so it's i think it's by the same people who did helvetica a few years ago is that
00:27:32.080
right um it's it's it's good it's a it's a it's a good movie on
00:27:37.200
design from a lot of different angles it's on netflix
00:27:43.279
great so last we're going to look at something called the kano model this is a product method
00:27:48.880
uh product development methodology um created by noriaki kano who is a
00:27:54.960
japanese professor who did research into customer satisfaction of products and he basically looked at
00:28:01.279
what are the attributes and features of products that have high satisfaction or low satisfaction and how do the
00:28:06.480
different how do the different uh features correspond there here's the model uh we'll look at it in
00:28:12.480
a little detail but basically there's four different ways you can classify an attribute of a product or a feature
00:28:19.200
the first is basic needs these are the things that you have to have in the model this is the green line
00:28:26.399
at the bottom if you don't have a basic need people are going to be dissatisfied
00:28:31.679
if you do have it people aren't going to care they're not going to notice it's kind of a neutral if you do have it
00:28:36.960
for example think of like the best possible bus driver
00:28:43.279
um just in their capacity as a bus driver not like a bus driver fights crime um what's uh what is what is your
00:28:50.240
happiness and satisfaction after stepping off that bus
00:28:56.000
okay um what about the worst possible bus driver what is your happiness or satisfaction after stepping off that bus
00:29:05.440
i think i think in api design i think a good example of a basic need
00:29:11.760
is uptime um if your service is down everyone cares everyone is upset if your
00:29:17.919
service is up people don't get excited that you're up unless you have a lot of problems uh um
00:29:24.159
like twitter maybe 2008 um instead they don't even notice they don't even think oh
00:29:30.480
the service is available right now um anyone have other thoughts on what kind of basic needs features of apis
00:29:36.640
might be
00:29:43.039
sure yeah just working doing doing doing what's advertised whereas if you don't do it's advertised
00:29:49.840
if you you know ask to charge 20 and you charge 40 you're probably going to be dissatisfied
00:29:58.080
no one expected side effects yep what else
00:30:05.600
principle of least surprise fast
00:30:12.080
not a performance bottleneck yeah if if you can't keep up with a customer people are going to be upset but if you
00:30:18.399
can they're probably not going to notice was this something over here complete say more
00:30:26.000
ah say more complete
00:30:34.080
sure yeah you you didn't you didn't release half the payment system but it actually you know works for every user
00:30:39.520
that you might have or every every type of uh interaction
00:30:46.000
flexible
00:30:51.919
um let's move on we can uh we can come back to um to all of these at the end um the
00:30:58.080
second type of feature or attribute um are uh what what what kind of calls performance
00:31:04.000
needs these are one-dimensional this is uh in the model this is the blue kind of straight line
00:31:09.279
these are things where if you don't have them people are upset if you maybe are average um people don't notice and
00:31:16.240
if you do it really well people get excited uh what are some thoughts on what could be uh performance needs in an api
00:31:25.120
speed i think i think for for it depends what you're doing i think for something like uh
00:31:30.960
long-running processes like video transcoding this is absolutely one if you are slower than average people say
00:31:37.360
complain is that you're slow if you're faster than average people get excited and say that you're fast
00:31:43.840
what else
00:31:53.360
what do you guys think do you guys uh um simplicity ease of use in integrating the api is that something that
00:31:59.279
scales linearly or follows a curve
00:32:05.840
i can see a case in aggregate for that being a linear kind of performance need if it's exceptionally hard versus
00:32:11.200
exceptionally easy people will uh people will care i think quality is an example so in
00:32:17.360
video transcoding if you uh if you compress video poorly and everything looks bad blocky people are gonna be
00:32:23.279
upset if it looks great if you can press better then people get excited um i think anything related to cost or
00:32:29.519
revenue would fit in here to you so if um your api if price scales or let's
00:32:34.880
let's say you're you're a revenue generating api you're an ad service or an affiliate network or something if you get someone more money they're going to
00:32:40.320
be more excited if you get them less they're going to be less excited
00:32:45.519
other other thoughts of these kinds of features predictable
00:32:53.919
having a consistent response that that's something that uh um how how is that a linear scale
00:33:06.240
sure sure yep yeah so being able to hit a
00:33:11.279
target bandwidth
00:33:17.039
sure it's a bandwidth would have a lot in common maybe with a um a speed or uh attribute
00:33:23.279
yep um next are features to which users are
00:33:30.159
indifferent they don't care if you have these or not this is sort of the gray box in the middle if you implement these people
00:33:36.240
don't care if you don't implement them people don't care what are thoughts of indifferent features
00:33:43.039
in apis what's that
00:33:50.399
soap who who here is indifferent to uh the use of soap
00:33:56.799
what else stuff that's not core tangential sure
00:34:02.080
maybe features that you know if you're never gonna use a feature you don't care as much about it
00:34:07.600
so then this is maybe one that's different for different users some users would experience something as a basic need some might be indifferent
00:34:17.359
what's that sure yeah great point on undocumented features if you build something awesome
00:34:23.440
and deploy it and no one knows they're not gonna care yep
00:34:33.280
uh are you saying that users are indifferent to google reader or google isn't different to google reader
00:34:43.919
all right um the last category are what conor calls delighters these are features that are attractive and
00:34:49.200
exciting this is the red line at the top of the graph if you don't have these people
00:34:55.040
don't care and if you do have these people get excited
00:35:00.560
these are i think i think this is where the condo model is most interesting i think oftentimes we think about getting to feature parity or you know performing
00:35:07.200
better but um actually there's a lot of interesting things actually a lot of the products
00:35:12.880
that we get excited about love or happen because they have these kinds of features
00:35:18.640
so in this encoder this feature for us was our api request builder we built this along with the
00:35:24.800
first version of the product we've kind of complicated api like 100 plus settings so we basically built a tool that lets
00:35:31.040
you explore every setting in the api and composes your api request you can copy and paste that into your
00:35:36.960
application and that's your integration this was maybe a week of work it was you
00:35:42.000
know some complex javascript but it wasn't that hard um but uh people uh consistently when
00:35:47.839
they give us feedback on our product this is one of the top two or three two or three things that they talk about
00:35:53.599
um i'm going to read some feedback on this uh we got an email a while ago unsolicited from a customer who said the
00:36:00.160
following i know the following statement is going to sound dramatic but it's the truth
00:36:05.520
zen coder seriously uplifted my entire day the api is really well designed and has documentation for not only what each
00:36:12.079
value should be but also for what an example or output would look like i spent the earlier part of the day working on a web
00:36:17.920
service that was the complete opposite of those things so when i started digging into zen coder i felt like i was
00:36:23.119
witnessing a double rainbow then when i found the api builder and went beyond the double rainbow to a level i can only
00:36:29.280
imagine is equal to witnessing a unicorn berth
00:36:36.320
so that that that would never have happened if we just built a service that performed and met basic needs that happened only
00:36:42.160
because we had spent the time to do sort of unnecessary things that made our product different and
00:36:47.839
maybe got users excited um making another example of this and this
00:36:53.119
is really really sad that this is the case but good support for software products for services for
00:36:58.800
apis i think is a sort of delight delight feature hopefully that won't always be true
00:37:05.440
and over time in theory at least the differentiator features become basic needs
00:37:11.920
so it was pretty amazing when they put wi-fi on airplanes right
00:37:17.040
10 years ago we would have said that that you know we would have sought out those flights now if the wi-fi is down on an airplane you get upset that's an
00:37:22.720
example of something going from an excitement feature to a basic need but customer support i think is is
00:37:28.800
something here and and anyone building an api product support pays massive dividends
00:37:41.119
why red instead of green for delighters uh i i just stole this off wikipedia so
00:37:46.640
uh yeah i don't know i don't know
00:38:01.599
it's true it's true that's true if anyone hasn't seen the louis ck bid on
00:38:07.040
that on i think it was on conan it's pretty it's pretty good it's pretty good
00:38:12.079
what are other thoughts of these sort of delighter features maybe specifically what have you seen in great
00:38:17.440
apis or great software products that fits this category
00:38:25.200
you feel like you're talking to another programmer in in support or in in what sorts of
00:38:42.960
if someone is actually if someone tries something out and is surprised by maybe the quality or or the success of what
00:38:48.800
happens it could be this kind of feature they might expect that they have to do a lot more work and find out if they don't
00:39:02.400
yeah great yep documentation that's actually populated with your account so put your api key in the sample request
00:39:09.040
or something about you know your usage profile what else what's that
00:39:16.720
sorry like an api router an api wrapper okay like like a ruby library or
00:39:22.000
sure what else
00:39:32.960
logs request logs sure yep yep you can actually uh you know if
00:39:39.119
you're designing the api why not store off every api request and let people go back and look through them especially the failed ones find out exactly what
00:39:45.839
they sent that failed uh maybe provide some ability to retry so let's say let's say it's a note a push notification like
00:39:52.079
replay that notification
00:40:00.240
development apis sure yeah like like a sandbox api uh an api
00:40:07.119
that you can play with without uh um yeah paying money yep yup
00:40:13.280
what what what what are some like getting specific what are some great apis that people have used and why
00:40:23.760
stripe who who's who is you stripe raise your hand who likes stripe
00:40:30.079
i don't think any hands went down um it's pretty cool stripe took something that we'd all been doing for a long time and actually just
00:40:36.720
made it good and that that making something horrible good kind of follows that red pattern there
00:40:43.040
what else what's that send grid sim grid twilio
00:40:51.599
zen coder i'll uh i'll talk to you later um
00:40:59.839
um so uh um kind of wrapping up condo kind of found in his research that the right
00:41:06.160
place to focus in building products if you want to increase customer satisfaction you invest in these you
00:41:12.079
invest in delight features and maybe a handful of performance features everything doesn't have to be high performance but you want
00:41:18.319
a few things you want as many things kind of in the top right of the chart as possible actually spending
00:41:24.160
time satisfying basic needs doesn't do nearly as much to make customers satisfied with your product
00:41:30.880
so getting back to the principles we've talked about minimalism we've talked about getting out of the way we talked
00:41:36.480
about designing for extremes we talked about being predictable and the fifth is
00:41:42.480
excite users apis are products nowadays apis are not just technologies and so if we want
00:41:49.280
people to use them and get excited about them we have to invest in those kind of things
00:41:56.079
um any any other thoughts before we wrap up
00:42:13.119
a concrete resource for specific things
00:42:20.079
how to build a great api um there's there's been a lot of activity uh in conferences and blogs over the last
00:42:25.119
couple years on api design any anyone know a great uh talk or post or something that that would be good
00:42:30.400
follow-up from this
00:42:36.880
white house github cool
00:42:42.800
design of everyday things which is a who who's the author of that norman is it
00:42:50.560
what is it yeah it's a a classic book on
00:42:55.760
just design in general which could be applied to software design product design api
00:43:01.520
design all right thanks everyone
00:43:44.160
you