Guiding Principles of Great Web APIs

All right. This is a truism. This is a thing that drives me every day. The best APIs aren’t written for the people you know. They’re written for the people you don’t know. They’re written for the people you will never meet. Not a lot of us have the opportunity to write those APIs. Often we’re writing APIs inside an organization, we’re solving our own team’s problems and so on, so forth. But for those of us who are aspiring to create libraries, APIs, frameworks, think of Vue, and all these other ones, you’re writing for people that you will never, ever see. How is it that you’re able to build something that’s useful, that’s helpful, that’s powerful, that helps them solve problems? Problems you haven’t even thought of? That is, I think, a noble goal, a noble course in life.

And the way I think about APIs in general is I think of APIs in a couple of ways. They aim for these things like global reach, like anybody in the world could use them. The adaptability, they can be used in lots and different ways, and they’ll be there for a long, long time. If somebody invests in energy in using your API, they have confidence that it’s not just gonna go away. You build on this notion of decentralization. The web is this whole idea of how we don’t all have to be in the same room, we don’t have to be at the same company. I don’t need to get permission from everybody else to do what I wanna do. It can grow, and it can emerge and it can get more complex. It doesn’t have to start out complex. And we’re gonna move beyond rigid interfaces and ecosystems that require us to buy all in just to start, to install lots and lots of dependencies, install lots and lots of tools, and program like everybody else. We don’t wanna do that. We wanna program like us.

The best APIs allow that to happen, but how is that done? What goes on inside the minds of people who build useful frameworks and libraries and tools? What is it that actually needs to be paid attention to? So, I’m gonna say today that I think there are five things that every great API or great framework or great tool or great library has. And there are five problems that we focus on, challenges we try to figure out how to meet. And it’s how we do that that I think makes things great.

Along the way, I’m gonna touch on five individuals that I think are really important to the history of our space of problem-solving on the web. And this is, we’ll gamify this a little bit. You can shout out if you know the person that I put on screen. Now, does anybody know this person? Probably not. This is probably the toughest one of the quizzes. This is Peter Morville. Peter Morville is a pioneer of information architecture, the way of thinking about the way we organize information in our heads. He’s written a great book called "Ambient Findability," but the one I really like is "Information Architecture." If you haven’t read this book, if you don’t have a copy of this book, I definitely encourage you to pick this up. He really thinks about this notion of discoverability. How do we know what is out there? How do we know how to find it? How do we know it’s gonna solve our problem?

APIs should be self-descriptive and discoverable. That means I should know where I can look for them, whether it’s Google or some other catalog, and they should describe to me exactly what it is they do. This tool is great for computing hashes, or this one is fine for computing net present value on property, or whatever the case may be. They need to be easily used, without prior coordination. I don’t wanna have to talk to you first before I can use your API. That means I need to leverage things like hypermedia, like forms and links that connect things together, affordances that explain, use this to submit a job, use this to compute the value, use this to add the tax, use this to pick the shipping. And that means I need lots and lots of metadata. If you think about HTML, there’s a lot more meta than there is info, right? There’s brackets and angles and heads and navigations and mains and all that. That’s metadata about the document. APIs need metadata as well.

Good designs increase our reach and our ability to share with and find and use the solutions of others. That’s a really important item. Does anybody know who this is? Gets a little easier, but maybe not. Nobody? This is Christopher Alexander. Does anybody know the notion of patterns? Software patterns? Christopher Alexander introduced the notion of patterns in physical architecture. Christopher Alexander came up with the idea that you don’t need to be an architect to build great buildings. We’ve been building great buildings for centuries without ever having an architect, right? And the buildings they build in South America are different to buildings that they build in Alaska. Why is that? Because they’re smart and they know what fits. There’s all sorts of great things that come out of Alexander’s notion, and I would say start with the book "The Timeless Way of Building" as a great introduction to his work. If you don’t have that, pick it up.

We need to design for unexpected use. How do you do that? How do I design for something that I’m not even sure people are going to need? How do I solve a problem I haven’t heard of? You make it possible to manipulate this item in a way that isn’t dangerous, so people can experiment. You provide affordances. An API provides you a whole bunch of different things that you can do. We don’t just say "use this URL." We say "this is how you submit, this is how you share, this is how you review, this…" It’s an action. We design with actions.

So, the web and Unix pipes are all about this kind of unexpected usability, the ability to compose things together, to bring things together, to use individual items to solve a particular problem. Good design makes well-designed services available for others to use in ways we haven’t thought of. In ways we haven’t thought of. We do this every day, with spreadsheets, and documents, and languages, and frameworks. We’re building solutions they did not think of. That’s a good design. That’s a good tool.

How about this person? Anybody know this person? Douglas Engelbart. Anybody heard of the mother of all demos? Douglas Engelbart did a demo in 1968 that showed off things that nobody had thought of in computing in 1968. In 1968, we were lucky to have mainframes, that filled up whole rooms. Douglas Engelbart showed off things like version control. He invented the mouse, in order to show on-screen connections, links, video capture, video in screen, so we could have discussions online. All of this was done in 1968. 1968? I think that’s more than half a century ago. And he was doing it before anybody thought about it. In his designs, he wanted to promote this notion of modularity, of collaboration, so that I can connect things together, they’re not gonna hurt each other, but they might help each other. He wanted to treat everything like a building block, everything like a tool. A great craftsperson has lots of tools in their kit, right? Saws and hammers and all sorts of, sometimes even specialized tools. I ride bikes a lot. There’s a whole series of specialized tools for bicycles. APIs are tools.

And this is, a lot of what he did is influenced by the notion of stigmergy. Has anybody heard of stigmergy before? Stigmergy is this notion of leaving signals for others to pick up. There’s a whole collection of animals, a whole species of animals called ants, that use stigmergy. Ants send signals to each other. Here’s food. Here’s where the nest is. This is what you need to carry, all these things. They give signals to each other. Great tools, great building blocks, send out signals that others can pick up on. Good designs make it possible for strangers to safely and successfully interact, so that I can use a tool and not worry that it’s gonna delete my data. And if I’m gonna make a change, that I can undo it. Interoperability and loose coupling is a sign of a great tool.

How about this person? Donella Meadows, a systems theorist and author of "Thinking in Systems," another great book on the notion of how systems work, and how complexity affects the way systems behave. APIs have to be designed for adaptation at runtime. They will change their behavior based on the information around them. That’s the stigmergy we were talking about. We don’t need big version jumps from version one to version two to version three. We just need to adapt over time. We need to adjust on the fly. You need to be able to reconfigure to make it behave differently. We need to be able to use hypermedia-driven workflows that are actually different for individuals. Servers will send out different links and different forms and different paths, based on who you are and what you’re doing. And that means over time, the whole system can change its behavior.

We need to build in feedback loops with clients. We know this through things like rate limiting and all these other features, but we need to build our own tools that way. We have a lot of traffic, I need to spin up more clients. I have not enough traffic, I need to shut down clients. I need to distribute this information to lots of different places. We need to be able to respond dynamically, and systems need to be able to learn over time, to be able to do something.

Good designs promote independent evolution on a scale of decades. It’s really challenging for many of us to work, to think about a project that’s gonna last 10 years when we’re working on projects where our deadline is Friday. But most of what we do that’s going to last a long time has to last decades. Angular, Vue.js, React, these are all tools on the scale of decades. And that’s what makes a great interface.

Anybody know who this is? Surely somebody know… Who? Roy Fielding. We got a winner. The author of the dissertation that defines REST. Now, what’s really interesting is the title of that dissertation is not REST. The title of that dissertation has to do with network software. Network software, not software that lives on a machine, but software that actually interacts on a network. And it’s the design and analysis of network software. Roy emphasized over and over again all of these things we’ve talked about, adaptability, and scalability and all these other things. And he built it into a kind of mathematical approach to judging systems. He wrote his dissertation to help us design new systems, and he gave us one example to try. He’s really, I can tell you, from talking with him, he’s really annoyed that we just keep using the one example. He had expected by now, 25 years later, that we’d have come up with lots of other examples.

We have to survive beyond individual implementations, whether I wrote it in Python or JavaScript or Rust or whatever. That doesn’t matter. We’ve gotta survive longer than that. REST constraints are all for long-term stability. He came up with a bunch of rules that he calls almost arbitrary rules, in order to make sure that the result was a system that was adaptable and scalable and stable over time. There’s no way to actually measure stability, but there is a way to measure whether or not it’s stateless. That’s the only reason he invented constraints. He didn’t invent constraints for all of us to just go follow. He invented them so that we would use them to get to the spot that he was hoping for, scalability. So, we need to design for evolving interactions, not fixed schemas, fixed URLs, all that other kinds of stuff. That doesn’t help at all. There are lots of computing environments that don’t use URLs. Are you gonna throw away all of this knowledge because there’s no URL? Of course not. Good designs, however, recognize that nothing is permanent, and things will change over time. We build in the adaptability for change. We wanna last a long time. It doesn’t mean we wanna build a stone. We wanna build something that’s alive, and that will survive, and that will grow and change over time.

So, what do these all add up to? What do these five principles look like coming together? I’ve kinda given you the hint already. Whatever you do, think about what’s gonna happen on the other side of the world. Think about that all the possibilities, all the connections you can make to help solve your problems, what else is out there, and leverage that in your own solution. And think about the people you will never meet. Think about what they will take away from your documentation or your API or your HTML. What will they see, when you put yourselves in the shoes of the user, as Carson has already talked about today? What is that like? What are they thinking? Can they use what you gave them? Do they need lots of handholding? Do they need to call you on the phone or write an email to you? Or can they do this on their own?

And think about the problems you’ve not thought about. That sounds weird, but it’s something to consider, all the time. What happens if somebody wants to use this to do something else? Is that okay? How can I make this safe for somebody else to use? How can I use my knowledge and my understanding of what’s happening behind the scenes to make it easy for people who don’t understand what’s behind the scenes to solve the problem that they have? Think of the great feeling that you can get from inventing something like the spreadsheet. That is a crazy piece of software, that was invented 35, 40 years ago, and it’s still solving brand-new problems today. That’s good stuff.

So, leveraging global reach means I have to make it very discoverable. I have to make it easy to find and easy to understand. If I wanna help people I’ve never met, I have to allow them to extend it in some way that I’m not in control of. They can write a plugin, they can write an add-on, they can use it as input or as output. If I’m gonna let people solve their own problems, I have to support composition in new ways. Ways to pipe one thing into another, ways to collect things together, ways to distribute things in multiple locations, and still work. And then finally, it’s gotta last a long time. It’s gotta be able to adapt and change. It’s gotta be able to be there when companies die, when technology dies, all sorts of things. That’s important. Talk about evolution and longevity. What about those spacecraft, Voyager, that has actually left our solar system? That’s longevity. That’s evolution. It should have died 50 years ago and it’s still running today. That’s great software that they put on that. They can still to this day, even though it takes almost 24 hours for light to get to that device, and even longer for signals to get to that device, they can still update the software on that machine, and make sure it still works. That’s great software.

So, this is my notion, this is my thinking. Discovery, extension, composition, evolution, and longevity. And there are lots of ways that you can implement that, in lots of formats and lots of places. I wanna leave you with one more thing. Who’s this? Huh? Alan Kay. Exactly right. Alan Kay. He’s a computer scientist, pioneer of object-oriented programming, and the person who first started to come up with the notion that there could be a laptop, that the computer that used to fill a room could sit on your lap. He’s an incredible inventor and thinker. And this is a quote that he’s said more than once. "The best way to predict the future is to create it." We have the opportunity to create our future. We can learn from others, and we can make our future different, not just for us, but for people we’ve never met. Now, in an interview, Alan Kay also pointed out, this is also a warning. Right? There are lots of people imagining what the future could be. Some of those people may not be so nice. And they may imagine a future that’s not so nice for everyone. So it’s important to be active, it’s important to be assertive, and it’s important to think creatively about what you can do to improve your future and the future of everyone around you. And I encourage you to do that. That’s why I’m in the business I’m in, of writing and researching and coding. It’s in order to try to create a future for lots and lots of people. Hopefully this has given you some ideas. I thank you very much for your time. Thanks a lot. Thanks.