Made by
Made by
Matthew O’Riordan
API design might seem to be entirely non-visual but Ably’s CEO Matthew O’Riordan argues that visual design has a great deal to teach us when it comes to designing APIs, in his talk at DevRelCon London 2018.
Well, thank you, everyone. Thanks for coming to listen. I think before I dive into, you know, how we can apply visual design principles to API design, I just kind of wanted to share sort of why APIs, to me, matter. So I’m the technical co-founder of a business called Ably.
We provide real-time APIs for developers. So in essence, our product is just an API. That’s the only thing we provide. And the way, you know, our customers judge us was on the quality and how their experience of that API. I’ve recently joined the OpenAPI Initiative, the board of API initiative. And also the AsyncAPI spec.
Both of these specs that are trying to define how people consume APIs and how we describe APIs. And interestingly, I heard earlier that the Open Source Initiative, it was their birthday, but it’s also actually the OpenAPI Initiative is their third birthday. So it was great. And the third thing is at Ably, we’re hatching up a plan to launch something this month, which is around encouraging developers to share data.
And what we mean by that is show real-time data. And that’s delivered through a program that we’re sponsoring, which is the open data streaming protocol program. And that’s delivered using real-time API. It’s obvious I care about the APIs that people use and open standards.
So, you know, given the context of this talk, I think it’s quite easy to fall into this trap of thinking that visual design principles only apply to visual interfaces.
So, you know, if you ask a typical developer, the people we’re talking to, you could very quickly think that actually the thing that, you know, they…I suppose the visual aspects of what they think about are, you know, the marketing collateral, the website, potentially, even the documentation. And I think that’s partly true. I think, you know, what we’re actually dealing with as developers, right?
And they spend most of their time, when they interact with us in our APIs, they’re spending most of their time in code, right? And those are the APIs that they expose to, and that’s the experience they have. So, you know, the same sort of design principles that we apply generally to visual design, you know, to things like documentation, which I’m sure we’ve all had experience sort of thinking about how we make that aesthetically better and how we lay their content out, I think you have to go through those same, the same ideas when you’re designing APIs.
And this is what this talk is about. So I don’t think anyone’s going to disagree that, you know, design is important. But I wanted to kind of summarize why I think design matters. And, you know, I kind of distil this down into three things. And, you know, even as a developer, I mean, you know, I’m probably happier sitting writing code.
But I sincerely appreciate the value of design, and the impact it has, and how it changes your perception of the thing that you’re interacting with. And so, you know, I think the first thing is really, when you think about design, design is function, right? Design is not just design in isolation. And Steve Jobs kind of coined this pretty well, which is, you know, “Design is not what it looks like and feels like, design is how it works.”
And, you know, I think if you embody that sort of thinking that the two fit together, right, like, good design and bad function, or, you know, great function but terrible design, will still result in a pretty bad experience. So, you know, I think the important thing to remember is that those two things together is what delivers a good design experience. And the whole idea of the design process is about also reviewing the function.
And, you know, I don’t know how many of you were around sort of 15, 20 years ago when doing sort of e-commerce integrations and all that, but, you know, I saw that, we’ll pay a sponsor thing. But interestingly 15 years ago, they were the leader, right?
That was the interface we had to work with. And to be honest, I mean, the developer experience wasn’t great, but then no one’s developers experience was great. They were probably the best of the lot. And you know what? What that did is Stripe came along. And I think what Stripe demonstrated is that they understood that design and function together is effective, right? So, you know, it looked good from a sort of visual interface for what they were delivering.
But if you look at what actually is really incredible there as they’ve distilled from 15 fields that needed to be filled in down to what visually is presented as one, which clearly isn’t, but that was powerful. And that really made a big difference when they came around that people, you know, developers were kind of proud to integrate Stripe because it was kind of embedded. It was beautiful, and it was very functional.
But, you know, I think what Stripe did which was really interesting is they…that sort of design and function, I suppose approach to everything, permeated everything they did, right? It permeated through how they interacted with developers. And, you know, so their APIs were intuitive. Their APIs was simple. Their documentation was fantastic.
They’re great examples. And, you know, I think a lot of what we are doing now is everyone is playing catch-up, and everyone is equally delivering great experiences. But they really were pioneers at the time. And I do believe, a lot of their success, can be attributed to their firm belief in design and function coupled together.
I think the next thing with design that we need to think about is that design has an amazing ability to kind of create a first impression. And, you know, everyone makes snap judgments, that’s just the way we work. And it’s very hard to change those perceptions once they’ve been made. So you now applying design principles to create the best possible experience for developers at the outset, from the first time they interact with the API is important and not fundamentally having a bad perception of your product that you then have to fix later on.
So, you know, I’m not saying let’s not fail, like, I mean, I’m not saying let’s wait and get it perfect, that’s not at all. It’s just, you know, let’s at least apply the best knowledge we can when we’re designing APIs and get it as good as possible. So I mean, I think, you know, the thing that I find really interesting is the automotive industry, when it comes to design, really embodies the power of design. I mean, if you look at the sort of those the Yugo from 1985, which was produced in the old Yugoslavia, you can kind of…just looking at that, it tells you a lot about the car, right?
And, you know, you can see that it’s clearly meant to be cost-effective, functional, and it’s not a performance beast, right? And the Ferrari on the right kind of says that, right? And all we have, the only thing we have to measure that is the design. And, you know, I think it’s really important that we think about what perception we’re creating. It doesn’t have to be the Ferrari but it could be…I want to be, you know, creating a perception of robustness.
I want to create a perception of easy-to-use, but you have your first chance. You know, when the first time a developer interacts with your APIs, that is the lasting impression you’re going to leave with them. And it’s very hard to change that.
And in the third thing, I think, with design that I think is really important, it’s about the fact that design allows you to amplify your message.
And, you know, the process of one of the things that you often hear designers say is, it’s about taking complexity and distilling it down to simplicity. It’s easy to do things that are complex or present complex ideas. It’s very hard to present complex ideas in a very simple way. So the design process encourages you to think about that.
And, you know, I think the problem as a developer is that you always have someone who says,” I need this new feature. I need this new method, I need this extra argument, I need some more attributes on the thing that I’m providing. And that’s a trap because every time you add, you’re actually reducing from everything else, right? I have three design principles here, and if I was on number 773, it would be pretty meaningless, right?
So, you know, every time you add, you’re actually subtracting from everything else. So I think it’s quite important to think about the fact that that design allows you to communicate a message, but you can only communicate so much.
So it kind of just really leads on to the sort of point of my talk is that, you know, API design is a new discipline, let’s not criticize.
API has been around for a very, very long time. But I think it’s only really in the last five years or so that we’ve seen huge successful businesses that a lot of what you can attribute to their success is by having amazing APIs, having good developer relations, having a good developer experience. They’ve valued developers. And I get quite involved in the sales process as well as sort of techie stuff. And I can tell you within the sales process, the interesting thing is the CTO will buy the product, but a developer has a veto, right?
If a developer says, “This API is just horrible. I hate the experience. There’s a better product I can use”. They can kind of veto their products. You know, the developers may not be the ones who are choosing the products necessarily but they certainly have a veto. And they have a lot of buying power.
So if we think of API design, it’s a new discipline. Because of that, we haven’t been sharing information about how to build APIs. And obviously, earlier, you know, with the Open Source Initiative, they were saying that, you know, DevRel has been around a long time really within the open source community, which is great. But how to build great APIs, and how to build those dev, you know, there’s developer relations programs, it’s a new discipline. So I think when you’re in uncharted territories, it make sense to look at other industries and see where they have learnt, you know, what lessons they’ve learned.
So I think visual design, graphic design, it’s been around as a discipline for probably about 100 years. And as a result, they’ve kind of distilled down to a core set of principles that designers will go and learn as part of their discipline. And I think we can pull on some of those because what design is about, it’s about communicating a message, right? It’s about creating a good experience.
It’s about creating perception of what your product represents. And it’s around distilling that down. So I’ve kind of pulled out what I think are probably the eight most common design principles. And there’s obviously a lot more than this. But you can see that, you know, these are the eight design principles that if you have to try and distil down, that’s probably the key ones.
I think in the context of API design, it would be a bit of a stretch to say that colour was something we could apply. And I would say alignment is also probably not really applicable. And then when I sort of looked at that again, I thought that individually, a lot of these concepts in the context of API design really can be grouped together. And I’d like to just sort of put the caveat here that I am…you know, this talk is really around applying this thinking to APIs as an SDK APIs, programming APIs, almost opposed to rest APIs or documentation.
But of course, the sort of thinking, this design thinking as we’ve seen with Stripe it’s a way of thinking, that can apply to anything. But for the purpose of this talk, I focused on code. So before I sort of jump into a bit of code examples, do you mind if I just ask hands up of who here is a developer and who’s here familiar with code? Okay. Well, good. I’ll demonstrate them.
Okay. So the first principle is hierarchy and proximity. The idea being that, you know, obviously, hierarchy allows us to group things together. If you think of a sort of discovery of a developer, I’m always like to think of…I like to sort of think through the API as someone using it with an IDE, right, with autocomplete. So you would type an object and you would go dot, and it would present the things that are available.
And that’s the hierarchy, right? So you’ll then have something else dot something else. And the grouping really is a concept that in design terms would be keeping similar things together because it makes sense. But I think hierarchy and proximity, you know, in the sort of an API design are roughly the same thing. So, you know, if we take this example here, you can see that a typical SDK, and sadly often generated by sort of code generators, would generate a pretty flat structure.
And that’s fine except, you know, in terms of cognitive load, there’s quite a lot to digest there, right? And going back to the thing of the idea of messaging, you know, what key messages are you describing, you’re not really describing anything, you’re just describing a bunch of methods that people can call. And so if you took that same code, and I am…this is all pseudo code and a pseudo Ably-like client library, but that’s not what it is.
And so the idea is if you take the things that relate to connection, and you bundle those together under the connection object, then you’d have client dot connection, and client dot channels, right? So now, you only have two things at the root level. So we’ve created hierarchy, and we group things together by, you know, bundling those methods within that object. And there’s a couple of tricks. I mean, from a code perspective, you can use things like overloading instead of having publish, publish back to publish encrypted, if your language permits, then use overloaded methods.
And that allows you to kind of keep conceptually the idea together whilst offering, you know, deeper functionality behind that. And, you know, if you look at this, this is kind of going back to this, you know, one of the first things I said is important about design, this simplifies how people consume APIs. You know, you’ve got to assume, I think, that not all developers are going to be reading documentation.
I tend not to read documentation. Some people go straight to documentation. We find, you know, a lot of our developers go straight to tutorials, you know, developers approach problems in different ways. And you have to kind of cater to all of those. And this is really about the kinds of developers who’ll discover it via the API itself or the source code.
The next concept design principles that I grouped together are contrast and balance. Once again, contrast as an existing code. And balance is really around, generally, in a design, visual design, it’s about how you distribute your elements, you know, either symmetrically or asymmetrically on the page depending on what kind of effect you’re trying to create. But I think it does apply to code because I think, you know, with contrast and balance, I think it kind of goes back to the whole thing of cognitive load, right?
The more we put into it, the less contrast each thing has, right? So the less we can show people at the time they’re discovering an API, effectively, what we’re doing is creating contrast. We’re creating something that stands out and something that doesn’t standout. And so we take an API again that, you know, looking at that would be a pretty normal API.
I have a publish method and a publish batch. And in there, what you see is, you know, I suppose it’s all, again, hypothetical. But probably what happened is that method started off just taking publish data, right, because someone just wanted to publish some data. And then, you know, a feature was developed. And they said, “Oh, we wanted to add push notifications because push notifications were the feature we wanted to add,” so you add another argument.
And then someone said, “Well, I needed some metadata,”so you added extras. And you can see what’s happening is that that method is as constantly getting the contrast, as in the thing that’s standing out there, there is nothing standing out. The only thing we can rely on at best is, you know, the alphabetical ordering of things. And that’s bad, right? So I think the thing that you can do with this is try and think about, don’t let the minority affect the majority of use cases.
So the 80/20 rule, but probably to the extreme, I’d say it’s the 95/5 rule, 95% of your people probably just need to use the publish method. And so provide the publish method, provide a way to dive in, and see more detail by accessing things like a message object with all the hidden features beneath there. I’ve been told I’m running out of time, so I’ll speed up.
Repetition and space, the idea is that repetition allows server developers reading your API. Once they’ve understood a concept somewhere, they can understand the same concept in another object. And, again, kind of with the cognitive load, you know, you’ve got an on connection method, connected method, maybe later need on disconnected. And these states will grow, right? And that dilutes the API because you’re creating more surface area over that API.
So, you know, you could do things like don’t have different methods. Even though they’re conceptually slightly different things, you can say have an event method which is on, and they have one method which is on, event, and that’s it. And it applies to both. So through the repetition of the same method names, you can kind of reinforce concepts.
So design checklist, I think, you know, the things that I would advise you do when you’re designing APIs is live in the developer API mindset.
Think about how they’re going to discover your API, and it may not be through documentation. It may be through your actual API. Use the three design principles I’ve mentioned. There’s a common concept of make your design invisible. If you can see the elements, if you can see things sticking out, then that means your design is not invisible. Good design means you can’t see it. The 80/20 rule, I just talked about earlier, don’t let a few use cases permeate the entire API and create more surface area.
Finally, a quick plug, we are sponsoring an open data stream program. The idea is that we want to encourage developers to share data, real-time data specifically. You can think of it a bit like a GitHub for data streams. So we’ve got a lot of data sources already in there, open date sets like flights information, and weather, and transport.
And the reason I’m plugging it here is that you all have DevRel programs, and you probably have APIs. And if you have data that is open data and you want to publish it through a platform for free and make it available to developers for free, we are sponsoring a bit like GitHub does for open source code. We’re trying to do the same thing for open data. And that’s me. Thanks a lot. If you follow me on Twitter, I will post up the slides afterwards.
Great. Thank you very much.