Designing great APIs: Learning from Jony Ive, Orwell, and the Kano Model

by Jon Dahl

In the video "Designing Great APIs: Learning from Jony Ive, Orwell, and the Kano Model," Jon Dahl discusses the importance of thoughtful API design, drawing parallels with industrial design, writing, and product development principles. He emphasizes that APIs serve two types of users: machines and programmers, each with distinct needs. The goal is to create APIs that are minimal, effective, and easy to use.

Key points discussed include:
- The Dual Users of APIs: APIs are interfaces primarily for developers and machines, and they must cater to the needs of both. Developers seek simplicity and clarity, while machines require data consistency and performance.

- Writing Principles Influencing API Design: Drawing from George Orwell's essay on writing, Dahl proposes that good writing principles can be applied to API design. Notably, simplicity and minimalism reduce complexity and make APIs more user-friendly.

- Orwell’s Writing Principles Applied:

- Good APIs should be minimal, "getting out of the way" to facilitate ease of use.

- Consistency in responses is crucial to avoid confusion.

- Industrial Design Insights: Dahl refers to Dieter Rams’ principles of good design, which include usefulness, aesthetic quality, directness, and thoroughness. These principles advocate for APIs that enhance user experience by being well-designed and aesthetically pleasing.

- Rams’ Ten Principles: Rams emphasized aspects such as being innovative, functional, and environmentally friendly — principles that Dahl relates to API design.

- The Kano Model: This product development methodology is discussed, classifying features into four categories: basic needs, performance needs, indifferent features, and delight features. Dahl highlights the necessity of addressing basic needs (like uptime), performance needs (like speed), and creating delightful features that enhance satisfaction.

- Customer Satisfaction: Investing in delightful features can significantly enhance user satisfaction, turning luxuries into standard expectations over time.

Dahl concludes with an emphasis on the importance of predictable, unobtrusive design in API development. Well-crafted APIs not only improve usability but also foster better relationships between developers and their tools. He encourages the audience to think critically about the principles discussed and how they can be applied in their own API projects, citing resources like "The Design of Everyday Things" for further reading.

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!