API Evangelist Conversation with Jamie Tanna, Engineering Productivity at Elastic

Hey there, Kin Lane, API Evangelist here once again for one of my API Evangelist conversations, where I bring in folks who are doing interesting things with APIs to kind of share what they’re working on. So let’s dive right in and see who we have with us today. Hey there, who are you?

Hey Kin, I’m Jamie Tanna.

What do you do, Jamie?

I am a number of different things. So I have ADHD, which also means that I feed into lots of different things. So I’m a blogger, I’m a software engineer, I’m a collector of open source projects, and I’m most noted recently for the oapi-codegen, Go API to Go code generator. It’s all my big loves.

Nice. Well, thanks, I appreciate you being here today. We were chatting in the, “APIs You Won’t Hate,” wait, is it “APIs You Won’t Hate,” “You Hate,” “APIs You Won’t Hate”? I always stumble there. Which is a great community, great Slack channel, I recommend going checking it out, everyone. And then you’re helping me with my site, I broke something, and then I was reading your blog and I came across an interesting post where you talk about versioning. But to set the stage, I want you to kind of help us, this is web APIs, you’re very specific, this is versioning and managing change for web APIs. What’s the difference, what do you mean by that, that precision?

Yeah, so there’s a mix, there’s both library APIs and web APIs. So library APIs I would see as, for instance, a Go or npm package that has a public interface that you as a consumer will use, and you will opt in generally to pull a new version of that dependency, which then at that point you would discover if anything’s broken. Whereas with a web API, that’s usually either distributed over HTTP or TCP, things like REST API, GraphQL, or gRPC, those are the sorts of things that you don’t really have as much control over, because for the most part a web API is something managed by someone else that you get access to straight away. Whereas, as I mentioned, with something like a library, you pull in that new version of the dependency, and until you’ve pulled in that new version you have the old version available.

Yeah, I think it’s important, I don’t want to assume that my audience understands what we mean when we say API, I think we throw that term around a lot. And then one more other fundamental before we dive in. So you’re heavily, we’re going to get pedantic today about what’s called semantic versioning. What’s semantic versioning?

So semantic versioning is a way of providing, as you say, a precise meaning to what a version looks like. So most commonly a version number looks like version 1.2.3, and in semantic versioning it describes a clear meaning to the one at the beginning. The first number will be the major version, then the second number is the minor version, and then the third is the patch. And so between each of these there’s a hierarchical and clear contract for consumers. So the idea is that within the patch version you would generally fix things, or introduce things that don’t provide any public-facing change. The minor version is generally, here’s a new feature that we’ve added, useful for you. And then for the major version, it’s, we have broken something, so beware. And so semantic versioning with web APIs is an interesting one, because for the most part people don’t care about the minor and patch version, they really just care, has something broken? And a lot of the times it’s useful to know is there a new feature available, but it’s primarily, is everything broken, and do I have to do some work to integrate with you?

Yeah, I think “do I have to do some work” is the critical part here for a lot of folks. And so what article caught my attention, and it deals with a policy I’ve instituted at several places where I’ve worked and consulted with, regarding where do you start when you first crack open an OpenAPI, you fill out the name, description, and you’re doing a design-first API in this particular case, or even a code first, but I would get teams come to me as a governance person, and that first version in the OpenAPI definition is 1.0.0. And so they’re starting out fresh, brand new, with a 1.0.0, because this is where you start, right, one’s the first. But your blog post goes into a lot of detail about why this is a missed opportunity, there’s a lot of work that has to happen before you can actually claim that 1.0.0 title. Explain what you mean.

And you brought up an interesting point. So as I mentioned, the major version, say version one, indicates has something broken. As computery people we like starting counting from zero, and so the zero major version basically says, anything could be breaking, beware. And it gives you a brilliant opportunity to say, I want to work out actually what my API looks like, what should my interface be for my customers and my users, and it allows you to break things safely. So you still have a communication tool in terms of, there is a breaking change, where you would, for instance, if you’re on your zero major version, you would bump your minor version, and that could either be a feature or a breaking change. So if people are using your API, they need to be much more aware and keep an eye on things a lot more, but it does also mean that you as the producer of the API can experiment. You can work out that something that you dreamed up at night and thought was a great idea actually is awful to work with for consumers who are coming from strongly typed languages, where they can’t reasonably describe your API in that type system. Or it could just be things like, you know what, it just doesn’t make sense, the way that your routes and everything doesn’t make a lot of sense. And especially, one of the problems with web APIs is they’re much harder to do breaking changes with. So I’d say especially with like a version zero, introducing those breaking changes, your customers and your users are going to be feeling those breaking changes every time they send a request. So at least make it clearer that you are a v0 API, makes it so your consumers can maybe be a little bit more defensive, and they can work out, okay, actually I’m expecting version 0.7, it looks like you sent version 0.11, so I’m going to try and do as much as I can with what I understand, but maybe they need to do some future work to actually pick up the new changes.

So it sounds like the work really has to happen on both sides. And that’s the purpose, is, we’re forced to immediately start thinking about breaking changes right out of the gate, what changes we want to make, and then our consumers have to kind of keep up with that velocity. And what other, you mentioned several other ways that this type of semantic versioning is communicated. So what other kind of ways do you recommend API providers use?

So as well as just the pure version number, which could be in like a header or a URL, there’s also things like your change logs and your release notes, having long and short form means to actually communicate to people. They’re a great opportunity to very visibly, like the top of the big release note, say, here are only breaking changes, please be aware that these things need to be done. And where possible, try and make it as actionable as possible, to help people understand, okay, these are the things I need to actually do. And even sometimes you may be fixing a bug, that there is a great XKCD about someone relying on holding down their space bar and it heating their computer, and they’re like, oh no, I use that to keep warm. And so one of the problems is people will start relying on functionality, so even if it’s a bug fix that you put in, someone may see that as actually a breaking change. So sometimes you actually need to call out those bug fixes more carefully, because some people may be relying on that functionality, especially before you’ve stabilized your API.

Yeah, I mean, we version to communicate change, and I think there’s kind of an art to it. I think people focus on the number a lot, and we’re being pretty pedantic about it, but it seems like it’s the wider package. And I know a lot of APIs who do it well and don’t do it so well. So who are some of, off the top of your head, the API providers you think do well?

So I had trouble thinking up some of these answers, because I think one of those things is, you shouldn’t really have to think about it, right? And there aren’t many that actually come to mind in terms of, I love the way you do versioning. But I will say, I know GitHub have recently started doing date-based versioning and clarifying that stuff. The way that, in particular, the Kubernetes ecosystem does it is they’ll have like v1alpha1, v1alpha2, v1beta1, and then they will go through different variations until they stabilize on v1. And one of the nice things about that is that’s very clear in the objects that you interact with in terms of what version it actually is, and it gives you that control to say, actually I do not understand this version, so I’m just going to reject it, or throw an error, whatever.

Yeah, yeah, for me, the one that tops, I wouldn’t say it’s a well-designed API, but it reflects the change, what I want to see, is the Amazon S3 API, like the PHP library I put in place in 2011, and it has the date 2006, some, you know, middle of 2006 is when S3 launched. And I think I upgraded one version in there and then it’s been in there for over a decade, and it hasn’t broke. So it kind of reflects what you said, is, we don’t really have to notice, you know, it’s good.

And actually that does remind me, Stripe have written in the past, so Brandur Leach, very brilliant person in the API community, wrote a really good post about how Stripe does API versioning, and they support every version in perpetuity. And I really liked that, like, for you as a consumer you don’t actually need to worry about versioning, because any of the docs that you see, they’ll work. On the provider side, though, I can imagine that is a very complex piece of work, because you need to be able to reason about things in dozens of different ways over the years, as your underlying models may have changed. You still have to think about it in terms of, okay, a decade ago we were saying this, so we still need to be able to represent it in this way.

Yeah, yeah, that’s, that sounds easy, can’t do that. I can’t say the same things I said a decade ago, I can’t do last week, you know. So, well, what keeps you coming in every day, why do you do this API stuff?

So I just, about a year ago, joined Elastic. I’m on one of our platform developer experience teams, and for me one of the things that keeps coming up is, I enjoy trying to make things easier for people to work with. This was something that over the last eight-ish years I’ve spent a lot of time on APIs, because it’s trying to provide that good developer experience that is consistent for people, that provides something that you can just look at and be like, okay, that seems reasonable. Generally you want people to be writing and reading docs, but also if it can be somewhat straightforward to read and understand how it should look, and to provide organizational standards in a way that things look and feel like a single suite of APIs, even if it’s built by a dozen different teams. And that’s the sort of thing that kind of gets me going, trying to keep on building good stuff.

Yeah, well, I applaud, I’m preaching to the choir, API governance is my focus, and not from a governance, more from a guidance and enablement and simplicity and consistency. So I think your approach to the versioning thing, which is often a very heated and ideological discussion, I find you kind of approach it in a very pragmatic way. So I appreciate you coming by today and sharing with me, thanks.

Thanks a lot.

All right, thanks a lot Jamie, that’s, goodbye. All right, another interesting versioning conversation. I got one already, I think it was last week, from Mike Amundsen, and they did a little of that backward work that Jamie talked about that Stripe had to do. And so I’m going to keep scratching at this versioning one, I think this is one of the most depressing kind of policies areas that I’m focusing on in managing change, and I think Jamie had a nice pragmatic and healthy approach to looking at things. So thanks everyone, until next time.