00:00:16.480
Um, hey everyone! My name is Jon, and today we are going to talk about designing great APIs.
00:00:24.080
As a little background, I work for a company called Brightcove. Brightcove specializes in video publishing for big media companies, enterprises, and small businesses, including startups.
00:00:30.800
I came to Brightcove via a company called Zencoder, which Brightcove acquired last summer.
00:00:36.399
Zencoder is an API-based product for video and audio transcoding in the cloud, focusing on high-scale, high-performance transcoding.
00:00:43.680
I have been working on APIs for the last three and a half years; that has been my entire focus.
00:00:49.520
Our product was also an API. Today, when I talk about API design, I am going to use some examples from the life of Zencoder.
00:00:55.039
I will also discuss my experiences, but I want to address other APIs and general principles as well.
00:01:00.079
Hopefully, everyone here knows what API stands for. If you don't, this probably is not the right talk for you.
00:01:05.439
Who here has worked on an API before? Raise your hand.
00:01:10.560
All right, that's almost everyone. That's great! Who has worked on an internal service-oriented architecture API?
00:01:16.720
What about an external productized API?
00:01:22.479
Good mix! Everything we discuss today will be equally applicable to both, and maybe we can discuss the differences between those approaches.
00:01:28.960
As you all know, the 'I' in API stands for 'interface', and an API is certainly an interface. We often think about this as a user interface.
00:01:35.119
If it were the 1980s, we might call it a graphical user interface; now it's just a user interface. But this is an interface as well.
00:01:41.360
Who is the user of this interface? Developers.
00:01:47.280
Are there any other users? Machines? Software?
00:01:53.200
I think every API actually has two users, each with different concerns: software and programmers.
00:01:58.320
What does the software user want? Data consistency.
00:02:04.479
Ultimately, it comes down to working as the machine expects, meaning syntax correctness, efficiency, speed, and scalability.
00:02:10.319
Now, what does the developer user want in an API? Ease of use. What else?
00:02:16.560
Simplicity, clarity, and understandable documentation, correct?
00:02:21.760
Ultimately, as developers, we want our APIs to be well-designed. We want to recognize that this is an interface for us.
00:02:27.200
It's important to think about the developer user when creating an API, just as a user interface for a website can facilitate usability.
00:02:33.040
A good UI helps users accomplish their goals and makes interactions pleasant; the same can be done with a good API design.
00:02:39.440
So, today we're going to discuss this through three lenses: the first is George Orwell, the second is Dieter Rams, and the third is something called the Kano Model.
00:02:45.440
Orwell will help us understand writing and how it relates to APIs; Dieter Rams will give us insights from industrial design.
00:02:50.879
Lastly, the Kano Model is a framework used in product development.
00:02:56.000
Throughout this talk, I will present five guiding principles that I believe should guide every well-crafted API.
00:03:02.640
We will explore specific examples, tips, and maybe discuss good and bad API structures.
00:03:08.560
I have been working on APIs for about three years, which is just a small part of all the experience in this room.
00:03:14.720
So hopefully, we can have an engaging discussion.
00:03:21.199
We’re going to start with George Orwell, best known as a novelist for books like '1984' and 'Animal Farm'.
00:03:27.120
Many of us, I'm sure, have read those, but he was also an essayist. He wrote what I consider one of the best essays on writing, titled 'Politics and the English Language'.
00:03:33.360
Why are we discussing writing? The quick answer is that programming has a lot in common with writing.
00:03:39.680
In fact, programming is a form of writing. Programmers take abstract ideas and make them concrete in a specific language.
00:03:45.840
This parallels what a writer does. For instance, Ruby gives us a grammar that allows us to express our ideas and create the work that we want our software to do.
00:03:52.160
So, what does an API do? I would argue that an API extends our language; it gives us new nouns and verbs to write things that are perhaps more powerful.
00:03:58.560
In Orwell's essay, he gives examples of good and bad writing and offers tips for writing with good style.
00:04:05.120
He also connects good writing to good thinking and bad writing to bad thinking, suggesting it's a political tool used in oppression.
00:04:12.000
As an example of political writing, consider the USA PATRIOT Act. What was this act actually about?
00:04:19.200
9/11, not patriotism. This legislation was given a name to obscure thought.
00:04:25.680
You can't have a rational discussion about the pros and cons of 'USA Patriotism' as a U.S. Senator.
00:04:30.560
Instead, this label shuts down discussion. This is an example of bad writing creating bad thinking, which Orwell argues is a tool of propaganda.
00:04:36.640
Here's another example from Orwell's essay. Imagine it was written by a leftist professor in England in the 1940s or 50s:
00:04:43.680
'While freely conceding that the Soviet regime exhibits certain features which the humanitarian may be inclined to deplore, we must agree that a certain curtailment of the right to political opposition is unavoidable during transitional periods.
00:04:50.560
The rigors to which the Russian people have been called upon to undergo have been undoubtedly justified by concrete achievements.' What is this really saying?
00:04:58.560
That's right: purges, gulags, and political oppression are acceptable. But instead of stating that outright, it's hidden behind convoluted language.
00:05:06.399
Here's another, less sinister example from academic literature. 'I am not indeed sure whether it is not true to say that Milton, who once seemed not unlike a 17th-century Shelley, had become, out of an experience ever more bitter in each year, alien to the founder of that Jesuit sect which nothing could induce him to tolerate.' What's that actually saying?
00:05:12.639
Interestingly enough, besides being totally incomprehensible, the fourth 'not' should not be there, and the word 'alien' should probably be 'akin'.
00:05:20.160
This demonstrates that even the author struggles to think coherently about their own writing.
00:05:28.800
Orwell gives six principles for writing with good style. Here they are: first, never use a metaphor, simile, or figure of speech that you are used to seeing in print.
00:05:35.200
Second, never use a long word where a short one will do; third, if possible, cut a word out.
00:05:41.200
Fourth, never use the passive voice when you can use the active.
00:05:47.440
Fifth, never use a foreign phrase, scientific word, or jargon word if you can think of an everyday English equivalent.
00:05:53.280
Lastly, break any of these rules sooner than say anything outright barbarous.
00:06:01.120
These principles are valuable not only for writing but also for programming and the design of products like APIs.
00:06:08.000
From this, I glean a couple of principles for API design. The first is that a good API is minimal.
00:06:15.680
As software developers, we contend with enormous complexity, often dealing with thousands, tens of thousands, or even hundreds of thousands of lines of code.
00:06:23.200
The best way to manage that complexity is to think clearly and write software that is simple, minimal, and clear.
00:06:30.000
For example, in the Zencoder API, there are about 150 parameters you can pass, including advanced settings for format, resolution, and bitrate.
00:06:38.560
These are micro knobs that few customers may use, but you can also just send a single parameter, and we will transcode the video based on smart defaults.
00:06:47.360
In this way, we make intelligent decisions about resolution and bitrate for cases where users do not specify them.
00:06:54.399
All of this complexity is there when needed, but we keep the default case as simple as possible, allowing users to layer on additional complexity as required.
00:07:01.680
The second principle is that a good API will 'get out of the way.' Just like good language and good writing should not call attention to themselves, neither should a good API.
00:07:10.400
A good API design should be direct and unobtrusive. For example, if you encounter an API that uses something other than REST, that's likely the first thing you'll notice.
00:07:17.200
Consistency is also a crucial principle. If you return a certain kind of response in one scenario, always return that response in similar situations.
00:07:24.000
An example: HTTP gives us two codes for authorization and authentication, but I've seen applications mix and match these codes inconsistently.
00:07:30.560
There are reasons for the existence of both codes, but it shouldn't be something developers need to worry about.
00:07:37.680
Any thoughts or questions on this so far?
00:07:45.760
Great, let's move on.
00:07:49.440
We’re now going to talk about Dieter Rams, who was the chief design officer at Braun.
00:07:53.440
He is one of the most famous industrial designers and has significantly influenced Jonathan Ive, the head of design at Apple.
00:07:59.280
Thirty years ago, Braun was the company synonymous with industrial design.
00:08:05.680
Jonathan Ive drew a lot of inspiration from Dieter Rams. As an example, I'm going to read a quick excerpt from an introduction Ive wrote for a book on Rams.
00:08:12.000
Ive recalls, 'When I was a young boy growing up in London, my parents bought a wonderful juicer. It was a Braun MPZ-2 Citromatic H.'
00:08:19.920
I knew nothing about Dieter Rams or his ten principles of good design, but as a little boy uninterested in juicing, I remember the Citromatic.
00:08:27.680
It was designed with shocking clarity—white, cold, and heavy; the surfaces were without apology, bold, pure, perfectly proportioned, coherent, and effortless.
00:08:35.200
You could clearly see it was made from the best materials, not the cheapest. At a glance, I understood exactly what it was and how to use it.
00:08:43.440
It was the essence of juicing, a static object that perfectly described the process by which it worked. It felt complete and right.
00:08:51.440
Imagine if Apple were to create a juicer—what would it look like? Perhaps something similar to that.
00:08:58.720
You can see the influence that Rams has had on Apple's designs. Here's a comparison: on the left, we have a Braun product, and on the right, an Apple product.
00:09:05.520
Now, let’s quickly go through Rams' ten principles of good design.
00:09:11.680
First, good design is innovative. Second, good design makes a product useful.
00:09:20.640
Good design is aesthetic. Fourth, good design ensures a product is understandable.
00:09:26.080
Fifth, good design is unobtrusive. Good design is honest, and good design is long-lasting.
00:09:32.480
Good design is thorough down to the last detail. Finally, good design is environmentally friendly.
00:09:39.440
Now, let's discuss how these principles relate to our work building APIs.
00:09:45.920
First, good design makes a product useful. Sometimes, we think of design as superfluous, something that can be added or omitted.
00:09:52.080
But this isn't true; everything created by humans is designed. There's good design, intentional design, and then there’s bad design.
00:09:58.400
Good design empowers users and enhances functionality, enabling everything that can be done with a product.
00:10:05.520
It is a key principle of industrial design to design for extremes, not just for average cases.
00:10:11.760
We should accommodate edge cases, and if we do that, the middle will likely take care of itself.
00:10:17.760
For API design, consider a product like Twilio. How would a power user, someone who has built telephony systems, use that API?
00:10:25.280
How would a Windows user encounter your Linux or Mac API? An API should be platform-agnostic.
00:10:33.440
Consider how a wrong customer might interact with your API. At Zencoder, we ensured that we are an API-only product.
00:10:41.760
We never set up a web page for users to upload videos, get them transcoded, and download them, as this would create a support headache.
00:10:48.960
By not allowing it, we kept only programmers as users.
00:10:56.560
Think about extremes and scale too. How would a user utilize your API at huge usage levels?
00:11:03.440
Consider both intentional use because they are big and accidental use, where a bad programmer writes an infinite loop.
00:11:10.560
At Zencoder, we've experienced this many times.
00:11:15.840
If you design for power users and for those less experienced, you will cover everyone's needs.
00:11:23.760
Next, good design should be aesthetic. This is often perceived solely as making things beautiful, which is true.
00:11:30.320
Good design should make products beautiful. Who knows what this is? Hungarian notation, anyone?
00:11:37.520
Who thinks Hungarian notation is beautiful? Ruby is designed to make developers happy.
00:11:44.480
Ruby is elegant and, arguably, the most beautiful programming language; even those who dislike Ruby often acknowledge this.
00:11:51.200
Good design also makes a product understandable. Imagine a fictitious API call: what if someone provides an API key that does not exist?
00:11:58.720
You could return a 500 Internal Server Error for an invalid API key, but that's not good practice.
00:12:06.160
Instead, return a 401 Unauthorized error that states that you could not authenticate the user due to invalid information.
00:12:13.040
You could also return an error message that includes specific validation information.
00:12:20.080
Here's another example: suppose a user's request is missing a comma.
00:12:26.160
You can return a 400 Bad Request for a malformed request. Why not go a step further and include a lightweight JSON validator?
00:12:34.400
This allows someone to see exactly where their request failed.
00:12:41.760
Good design should communicate clearly and directly to users, creating less ambiguity.
00:12:48.560
For example, if your service is unavailable, provide clear instructions for the user on what actions should be taken.
00:12:55.840
Good design should also be unobtrusive. This means that it should not be cluttered, and indicators should only appear when they are useful.
00:13:02.960
It’s often more challenging to achieve minimal, unobtrusive design, but it will enhance user experience.
00:13:10.560
Finally, good design is long-lasting. When beginning to build an API, you may not know how far it will go.
00:13:18.560
Version your API from the start by simply scoping with a namespace, rather than later introducing a complex versioning system.
00:13:26.000
Using UUIDs rather than incrementing integers for primary keys can also assist in scaling your API.
00:13:34.799
Good design is also minimal guide design—that sums up Rams' philosophy and aligns with Orwell's insights.
00:13:44.799
Good design is minimal; it gets out of the way and is predictable. Without even knowing an API, you can guess how it might work.
00:13:50.480
For example, how does the Stripe API work?
00:13:58.120
You can guess it is a secure HTTPS call to api.stripe.com/v1/charges, with parameters for the user, amount, currency, and other necessary information.
00:14:05.440
This level of predictability saves developers time. They shouldn't have to guess how an API works.
00:14:13.040
Now, let's look into the Kano Model, a product development methodology created by Noriaki Kano.
00:14:21.240
This model analyzes customer satisfaction, exploring the attributes and features of products that correlate with high or low satisfaction.
00:14:28.000
The model classifies product attributes into four categories.
00:14:35.760
Firstly, basic needs: these are the essentials. If basic needs are unmet, people will be unhappy, but having them met results only in neutral feelings.
00:14:43.920
For example, think of the best bus driver—stepping off that bus, how satisfied are you?
00:14:50.400
Now consider the worst bus driver—what is your happiness level then?
00:14:57.200
In API design, uptime is a critical basic need. If your service is down, everyone cares and gets upset.
00:15:05.200
If your service is up, no one acknowledges it unless you frequently have outages.
00:15:12.560
Next are performance needs—one-dimensional attributes. If not met, they cause dissatisfaction; if met, users don't generally notice.
00:15:22.280
If you exceed expectations, however, users become excited—speed is a common performance need in APIs.
00:15:31.600
Besides speed, simplicity and ease of integration are also important—if achieving that is exceptionally difficult, users will care.
00:15:39.440
Quality is another performance metric. If video transcoding results in blocky images, you will lose customers.
00:15:47.760
Next are indifferent features; users have no strong feelings either way about them.
00:15:54.960
An example could be SOAP; who here is indifferent to its usage?
00:16:02.560
Finally, we have delighters, which are exceptional and exciting features.
00:16:07.240
These features are noticed and appreciated, even if their absence doesn't frustrate users.
00:16:14.080
One example at Zencoder was our API request builder, a tool that simplifies the complexities of a comprehensive API.
00:16:22.400
This was a relatively simple feature to implement but immensely appreciated by our users.
00:16:30.080
I want to read some unsolicited feedback we received: 'Zen Coder seriously uplifted my entire day; the API is really well designed and has documentation for each value, along with example outputs.'
00:16:37.840
Another example of a delighter is excellent customer support—it enhances the user experience and satisfaction.
00:16:45.760
Over time, delightful features can evolve into customer expectations.
00:16:52.880
For example, Wi-Fi connectivity on airplanes was once exciting but is now typically expected.
00:16:59.920
In summary, investing in delight features and some performance needs can greatly enhance customer satisfaction.
00:17:07.040
Reflecting on the principles discussed: minimal design, unobtrusiveness, and predictability are key to effective API design.
00:17:14.480
Any final thoughts before we conclude?
00:17:20.960
A few useful resources on building great APIs have emerged recently, including conference talks and blog posts.
00:17:27.840
Has anyone come across effective talks or articles on API design?
00:17:34.480
Design of Everyday Things, a classic by Norman, is a resource that applies broadly to product design and could apply to APIs.
00:17:41.680
Thank you all for your time.
00:17:53.360
I'll be here for any further questions.
00:17:54.880
Thank you!
00:17:56.480
Thank you.
00:17:57.680
Thank you!
00:17:59.680
Thank you!
00:18:00.560
Thank you!
00:18:01.920
Thank you!
