Table of contents:

Driving API Adoption

• What are the must-haves if you're launching a new public API at your company?
• After launching your API, how do you gather and prioritize developer feedback?
• What metrics do you look at to understand API health?

The State (and Future) of APIs

• How do you see the API landscape changing in 2023 based on the startup tech market right now?
• How do you think the emergence of AI will affect the API landscape?
• How can employees make an effective argument for getting more resources for API efforts?
• When should you consider switching API service providers?

API Usage and Accessibility

• How can API documentation best serve a diverse audience of both technical and non-technical consumers?
• What guidelines do you use for deprecating vs. maintaining old API versions? What’s the best way to smoothly sunset old versions and get users to upgrade?
• What are your biggest pet peeves when it comes to APIs?
• How are customer stories and their ReadMe usage impacting what ReadMe is building next?
• What are you most excited about in your 2023 roadmap?

Dave: Welcome to the ReadMe and AWS joint AMA today. We're going to be talking about (surprise, surprise) APIs. If you're unaware, Amazon and ReadMe are now officially partners and have been for about six months. It's been a great relationship so far. We're partners in, of course, a marketing capacity, but also in a product capacity. We'll touch on the integrations we've built today, but mainly we wanted to use this opportunity as a chance for folks to ask Greg and Josh, who've really been leading the technical side of this partnership, questions about APIs and in general.

We asked folks to send questions in beforehand and got a bunch of great questions that are bucketed into a few themes. So we'll get to those one by one and then we have some time at the end for if anybody thinks of any questions during this or didn't get a chance to submit their questions. I'll let these guys introduce themselves. Josh, do you want to kick it off?

Josh: Yeah, sure. Hey everyone, thanks for joining. My name is Josh Nickerson. I lead the Product Management team for Amazon API Gateway here within AWS. I've been with this team since July and been at Amazon for about five years. Previously worked in Alexa AI and then also on the smart home side of what Amazon does. So excited to talk to you.

Greg: Nice. And my name's Greg. I am the founder of ReadMe. So my background just before this was engineering and I kind of slowly built ReadMe and people started using it and here we are a few years later. And Dave works at ReadMe. Dave, what do you do?

Dave: Yeah, I've been at ReadMe almost six years now. I was our first sales guy and now I lead our sales team and our sales efforts. Been in APIs on the go-to-market side for about eight years now in total. So it's been a fun ride.

A little bit about the partnership. The goal of the partnership was for joint customers to be able to deploy a great end-to-end API lifecycle solution. Obviously with Amazon Gateway, you can create and maintain secure APIs within the Amazon infrastructure. And then with ReadMe, we can be that public display layer, where you can showcase those APIs and the documentation and give your developers everything they need to build a great integration and be happy using your public APIs.

And I have a pre-sent message here, on the next two points. We've built two integrations so far. One is the ability to sync API definitions from Gateway, which are generated in Gateway, automatically into ReadMe. So there's documentation on how to set that up. It's a really nice integration, it's easy to set up, and it removes a step where typically you have to create a spec, host it somewhere, then write the CLI tool to send that spec into ReadMe. This removes that hosting it somewhere, CLI tool step, where you can sync them directly from Gateway into ReadMe.

We recently launched a second integration. It's a webhook where you can surface API keys to your developers that are using the documentation. This is really nice for developers that want to make live API calls with their actual API keys, whether that's for your sandbox or production environment, right in the docs. There's a little toggle for if you'd like to provision API keys for your developers in the documentation. So if you want to have a full self-service API experience where your developers come create their own keys right from the docs, you can now do that with the webhook that we built together.

Moving into the questions, we noticed some themes, so we bucketed the questions into these themes. Starting off is driving API adoption.

Driving API Adoption

What are the must-haves if you’re launching a new public API at your company?

Josh: Yeah, I think there are a lot of considerations you would have. The top things that come to mind from my perspective are availability and security, which we see as our core value proposition. From the availability side, as you launch the API, you should have a good understanding of what kind of traffic you’re expecting and be confident that you can handle it. Whatever infrastructure you're hosting it on, whether it's us or another provider or on-prem or something else, you need to know it's not going to tip over when you (hopefully!) get the huge surge of customer interest that you're hoping for and you've got hundreds of thousands or millions of people hitting this endpoint. You need to know it's going to be stable. That's an important consideration.

The other one is security. The threat landscape out there is kind of scary. APIs are the front door. As you launch this first API in this kind of scenario, you want to be confident that you're not opening up your systems to some kind of data breach that could tank customer trust and create an existential risk for your business. You want to make sure that you're buttoned up from that kind of perspective. Those are the first two that comes to mind for me.

There's also one around the sort of authentication authorization setup that you have. Is this just a totally open API that anyone can hit? Or do you have some sort of mechanism in place, where, for someone hitting that API endpoint, you know who they are and that they’re allowed to make that sort of request?

And maybe this is more in Greg's realm, but how are folks going to find out about this? Are you going to run an email campaign? Or, for your first API, maybe an email campaign works well, but as you're going to do more and more of this and have multiple APIs and package them into products, you're going to need a scalable mechanism there and that's where something like ReadMe can come in.

So those are a few of my thoughts. Greg, maybe I'll kick it over to you with that segue.

Greg: Thanks Josh. I'm going to go completely the opposite direction, which is a good reason why we're working together, because we have different things we get excited about and care about. I think one of the biggest things before you start — and this going to sound really simple — is having really good use cases of why someone would use your API. All the time, I see people launch an API and no one uses it because the endpoints just don't make sense for any use cases. People sometimes build an API and they just replicate the functionality goes to the UI. It's like, okay, so it's the UI but with extra steps. There's no thought behind, why someone would actually want this API. I know it sounds really kind of crazy, but I see so many APIs where no one has any use cases, so you end up building endpoint that don't really make sense, you can only get 20% through what you need to do. Stuff like that.

Then you're like, "Why isn’t someone using our API?" You think, "Maybe the docs aren't good enough or maybe the API doesn’t..." And you keep going down this rabbit hole. But really the answer is, you haven't really thought through what the point is behind building this API. I think we've gotten to this point where APIs are so ubiquitous that everyone knows they need an API. So people are like, “Yeah, we need an API, for whatever reason.” I think everyone has this “build it and they will come” mentality sometimes. Like, well, why wouldn't people want to build on top of my brilliant company that everyone loves? When, in reality, it's a lot harder than that. You're asking people to dedicate resources, time, effort; they have to trust you for years to come.

A lot of times people just throw an API out there and think, "Oh, the community will build beautiful, amazing things on top of it." But people aren't creative like that, and I don’t mean that in a bad way, because I'm not either with other people's companies or products. I'm not going to sit here and come up with the use cases for why I would use someone's API, because I've got a lot going on. I've got my own company to run, I've got my own things I'm doing. I don't want to build something for someone's API on someone's API. You need to make sure there are very clear use cases to get people excited and then, when you're building it, you can accommodate those use cases.

All the time I see endpoints where you literally can't do the things you need to do, because the endpoints are so specific and they don't work well together. You basically just copy just a very straight-up RESTful model, where you can get an endpoint or list an endpoint, stuff like that. You’re just untethered from what people might want to build. So make sure you have some solid use cases and you can use your API to build those out and give people good head start there.

After launching your API, how do you gather and prioritize developer feedback?

Josh: I think there are a couple pieces here. The first is, what's the input? How are they going to give you this feedback? Spend some time thinking about the mechanism there. They're using an API, right? So, is it something that you build into the API? Is it something where the UI they use to learn about the API and explore documentation has a functionality through which they can provide feedback? Are they emailing you? Is there a support team that you have? What's the sort of mechanism there? Then, make that as easy as possible.

Ideally, as they're using the product, something happens they want to give feedback about. Generally on the bad side — it's rare that people provide good feedback just saying, "Hey, this is great, I love it." It's nice when that happens, but when something goes wrong, you want it to be as easy as possible to send feedback, where they don't have to switch into a whole different interface to provide feedback or remember to do it later. It’s just something like, I can give you a thumbs up or thumbs down right now and you can correlate that to what I was doing. That's the first part, is that input.

On the second side, when that feedback comes in, what are you going to do with it? There's the prioritization mechanism and then there's how you’ll track all those issues that come in and tag those into your dev team sprints and those types of things. That way, assuming that there are some things that customers would like changed, you can act on that feedback. I'm a PM, so we can go into prioritization frameworks, but different companies have different ways they like to do that. You'll think through how many folks it impacts and how much it impacts them, as well as alignment with just your overall company goals and north star vision. That's all going to come into play as you think through, is this really something I want to dedicate resources to changing?

Greg: As a former developer (or, once in a while, current developer), I think there's a mentality for developers, where you become a developer because you just figure things out and you keep pushing and pushing and pushing. I think developers are probably the least likely to raise their hand and ask a question and are more likely to either, A, assume it's their fault, or B, just get frustrated and move on and vent about the product or API to other developers. When I man our support queues, I don't see a ton of feedback from developers, it tends to be from other people.

With that in mind, I do think — and maybe Josh has a different experience, because I think AWS does a very good job of soliciting feedback — but I do think developers almost forget they can email support. They have a very self-sufficient mentality a lot of the time. Again, that's why I think docs are incredibly important, because that's part of how people figure things out. But there's also jokes about engineers, about how an engineer would rather copy and paste a code snippet and torture it into working, rather than just reading the two paragraphs below it. There's a lot of this “just figure it out” mentality, which first of all, is a really good thing. That's how you become an engineer is you just want to figure things out. But also it can be a little frustrating.

With that mind, I agree with that Josh said, but also I think just monitoring and watching. We have a certain endpoint that frequently errors out. This is intentional, because if you upload an invalid OAS spec — which happens a lot because OAS is confusing — then the API should respond with an error. And we never really did much about it. Then, I started tracking it and posting every single failure to Slack and started reaching out to everyone in it. All of a sudden, people who had just given up and moved on from ReadMe because it didn't work, started responding. It was one of the best things we did as far as getting feedback and making things better, because things were just silently failing and engineers were getting frustrated. They were moving on or figuring something out on their own, or maybe spending two hours on it and they would end up getting it working, but they were frustrated for those two hours.

By watching it and being proactive and reaching out to people, first of all, they all thought it was magic. They'd always be like, "Oh, are you a bot?" And I was like, "No, I just actually watch the channel and reach out to people when I see errors." We end up with a lot of customers who benefit from it. So while I agree with everything Josh said, I think it’s important to also realize that a lot of developers aren't going to say anything and find ways to force them into raising their hand and giving feedback.

What metrics do you look at to understand API health?

Josh: That’s a good question. There are obviously things around engagement and growth relative to whatever targets you have for the API. This can be from an internal sense — if this is an internal API we want developers to be using, because it makes them more productive, or more generally an external kind of productized API. How many folks are using it? Is that growing? What's the adoption look like? That's obviously important.

There's also these operational things that you would want to monitor in terms of error rates. Are we seeing fatals? What is that trending like? Latency relative to where you want it to be? That latter part is important. There's latency, but there's also, what kind of latency do customers need? Is this an API that's part of a gaming application where that's pretty sensitive? Or is it more like, well, the API latency doesn't really matter because the backend integration time is 30 seconds anyway. That's something you want to look at too.

I think those are some top ones that come to mind. Obviously depending on what the API is, there are others that can come into play from a security perspective or a monetization perspective. But I commonly I see those as the top ones.

Greg: I think APIs are interesting because it's really easy to look at a graph and see that, okay, 98% of our calls were considered successful and think, "Okay, that's really, really good." But where that falls apart is, it's really hard to dig down and see, because people make so many API calls. If you go to a website and click around, at most, you can click, what, 10 pages in a minute? That’s if you're flying through a website. But with APIs, if one customer is making hundreds of thousands of requests, and they're successful, all of a sudden the metric's really high. It's so easy to miss a new customer trying to get onboarded and they get three 503 errors. That would never register in anyone's metrics because it's three 503 errors is nothing compared to 200,000 successes. It's easy to look at a graph and be like, "Oh, okay, things are going great. It's almost 100% success rates.”

But you risk losing those early people. People interact with APIs in lots of different ways, but two major ways. One is they're sitting there and hitting go and trying to get a response back to get it set up. There's actual developers sitting there and doing it. And then there's out in the wild. It's in production and it just runs behind the scenes and no one's doing anything. A customer might hit it or a client job or whatever it happens to be. It’s important to really separate out those scenarios — this is a human being who's tweaking it and changing it and trying to make something happen, but they're having errors or they're having successes. You need to separate those incidents from, okay, this has been running like clockwork for two years now. Because otherwise it's impossible to really dig into those new customers who are just having issues.

I agree with everything Josh said as well, but I want to add, I think it's really important to realize that every failed API request is some real person trying to do something for real, for their customers, for themselves, whatever. You want to make sure it's easier to highlight those very few small amounts of errors, especially when it's someone trying to get started for the first time.

The State (and Future) of APIs

How do you see the API landscape changing in 2023 based on the startup tech market right now?

Josh: Yeah, I think first it's important to recognize that this whole cloud thing, this whole serverless thing, it's all pretty new. You look at most applications are still on-prem, are these legacy monoliths that companies are trying to decompose. The move to microservices, the move to API first, the emergence of this API economy is a pretty new thing. This heavy reliance on APIs — I think that's a trend that's going to continue and only going to get bigger. This mentions the market right now and what's going on with the economy. It's probably going to accelerate this year because fundamentally companies do this, because there's cost savings from it, where they don't have to run an in-house data center or where their developer teams can be more productive by decentralizing things and making it more modular with microservices. And that ability to move faster becomes important when there are things going on with the economy. So that's one trend that I would expect to continue.

There's one around security. As the API economy grows, the threat landscape and the number and capability of bad actors out there trying to do nefarious things, it’s not getting any less scary. I think the emphasis on security, particularly around APIs, is going to continue and there will be more scrutiny around things like data breaches and protection of sensitive data. That's going to be a big theme that's going to continue this year.

A third thing I'll mention is the emergence and refinement of industry specific types of API standards. We've had things like OpenAPI, but we're seeing things like open banking, open charge point protocol, fast healthcare interoperability requirements. There are things that are industry specific. For example, there are government types of customers in public sector where, if you're building an API in this kind of space, it needs to meet these requirements to meet this standard. Companies are having this compliance that they need to enforce that's being required by their regulators. From an API provider perspective, it's something that folks are going to be looking at and thinking through — how can we make that easier for customers where they don't have to think about all of those requirements? They can just use something and it's either less effort or it comes out of the box. Those are a couple things on my mind in terms of just the landscape in the market.

Greg: I'm going to side step this question a little bit and not talk just about this year specifically. Because I don't think there's much really to say about how the economic climate and stuff like that are going to affect APIs specifically. But I do think that my whole premise around starting ReadMe and getting into this is that I've always believed there's going to be, not a complete convergence, but a convergence between traditionally non-technical and technical people. If, 10 years ago, you said that you spent all day working on APIs, it would be easy money to bet that that person's a developer. They probably have a computer science degree and probably went to college for it. They're probably a pretty deeply technical person. But now, if you say, "Oh yeah, I do API stuff," that doesn’t necessarily mean that. For example, Dave. Dave's not engineer, but all the time people will come to me after a meeting with him and say, "I talked to Dave for 30 minutes and I didn't realize he was a salesperson, not an engineer."

The distinction between technical and non-technical is getting increasingly blurred, because people are becoming more technical just because they grew up with computers and around technology. But also tools are getting more easy to use. People who never could have built a startup 10-15 years ago can now cobble together a few APIs and build something pretty good pretty quickly. Or even personal workflows, with companies like Zapier. They make it so you don't even think of it as an API company, and make it easy for anyone can build API stuff. It's always annoying, for example, I built a custom bot a few years ago for Slack stuff and it stopped working for whatever reason. And Sarah, our marketing director, replaced it with Zapier in 20 minutes. And I was like, "But I spent so much time on this and you just fixed it in 30 seconds." I think that's really cool that more and more people can take advantage of the stuff that traditionally has been locked up in this archaic knowledge.

The last thing I'll say is that I'm also really intrigued by these companies that are realizing that developer tools don't mean the rawest ingredients possible. For example, it's kind of like being a chef, you might think, okay, I need all the rawest ingredients. But then you have these companies like HelloFresh and Blue Apron, where you get pre-measured stuff and it all fits together. And no longer do you have to go to a supermarket and figure it out from scratch, you get these pre-built kits. Then there are also restaurants that serve food that's been made for you.
I do think this ability to choose your own adventure of how complex it's going to be, obviously more complex means more stuff you can do, but lot times people don't need that. I think Stripe and Twilio have done a phenomenal job of having these raw materials that you can use. You can go real raw, or you can just copy one line of code and paste it in and you get a really nice UI with Stripe's components. I'm seeing a lot of that where people are kind of doing choose your own adventure, where if they want to go make raw API requests and get back like JSON blobs, heck yeah, go for it. But if you just want to get something done, no one's ever wanted to use your API. They want to do something that your API enables them.

And I think those are such a cool ability for dev tools to be for all levels of people and meet them wherever. The best dev tools, the best APIs, are the ones that go really low level, go really high level and they can meet customers at every single level based on what they need. I think that's going to happen more and more over the next few years and that's what gets me excited.

How do you think the emergence of AI will affect the API landscape?

Greg: What's most fascinating to me is that, and this kind of dovetails into what I just said — I don't know if anyone here has ever used, for example, OpenAPI's API, but I’ve spent a lot of time with it and it is incredibly frustrating as an engineer. The way you interact with it is with prompts, which you basically write in plain English. For me, as an engineer, I'm like, this is not deterministic at all. Deterministic meaning if you run it five times, an API should return the exact same thing five times, unless something's changed behind the scenes. But if you run OpenAI five times, you get completely, wildly different answers sometimes and you have to tweak the prompts and there's no syntax that goes with it.

The reason why I'm saying I'm frustrated by it isn’t because I don't think it's great, I'm frustrated because it's so good and so fascinating and so interesting. It's going to change how people think about interacting with the system. Traditionally, the way we've always interacted with systems is that we let the computers do most of the decision-making about how we talk. I can talk to other people and they can understand what I'm saying, but computers need very specific structure. ReadMe's built on this fact that you need to send very specific instructions the exact same way and we help you understand those things.

Whereas AI's fascinating, because we flipped it. None of us think in gets and puts and posts. We do that because it's kind of a negotiation between us and computers, where we found the syntax that computers can understand, but also humans can. Engineers worked our brains into thinking we understand this code, which we do of course, but we're doing it on the computer’s terms. Most of the things we're doing is because computers can understand it.

So I don't have an answer other than I do think it's going to bring more and more people into the field and make it easier to do things. I'm so fascinated by what interacting with computers is going to look like in 5, 10, 15 years, because we've been doing it on computers' terms so much. Josh, what do you think?

Josh: I was in Alexa AI for three years. I owned the internal machine learning platform that all the Alexa scientists and engineers used to build a different model. So, this is a very interesting topic to me, and I have two thoughts. One, dovetailing with something Greg said earlier, I think AI and the emergence of AI is going to make it easier for people to build APIs. Before, you had to have all this expertise, but there's been kind of a shift. Now, there's some developer tooling that makes that easier, but you still have to have some expertise to go to this prompt and say, "Hey, I'm trying to build an API for this and here's my use case. Show me the request response structure that should look like. Show me what the documentation should look like. What kind of off should I use? Where are some places I could consider hosting it?" And you just get all this information back, and the next step is like, "Okay, just do that for me." So I think it's just going to make it a lot easier. That's just going to accelerate the emergence of APIs as the sort of communication mechanism between services and applications.

The other thought is a lot of what's happening in ML kind of parallels a lot of what happened almost a generation prior in software where there's the emergence of ML ops analogous like devops and how do you track the sort of evolution and lineage of a model across its life cycle from raw data to a model in production? So there's the whole ML ops thing, there's a whole ML governance thing that's coming into play with, okay, you've got all the data that's used, which is the basis of machine learning, and how do you really understand where that's coming from? So APIs play into all of this, with how do you track these things? So there's going to be a relevance as you're building APIs. Does that enable an ML driven use case for some company that's out there? Does it plug into their data pipeline or their ML ops or whatever it is, it's something that you also going to have to consider as far as thinking about the business case for an API. So there's a couple thoughts on it.

How can employees make an effective argument for getting more resources for API efforts?

Josh: There are two that come to mind from the way we operate at Amazon. One is being data driven, so you have to bring the data. If you're going to make an argument to your leadership along the lines of, "Hey, we want to build these APIs or we want to do this thing around our API landscape, we need some resourcing for it." You have to understand what's the ROI and at least be able to talk to it. That could be in terms of a cost savings aspect or maybe it's going to cost more actually, but it's going to let us move so much faster because it's going to enable us to decentralize things and enable dev teams to move independently, versus having these internal dependencies they're fighting over, or something like that.

It’s important to at least being able to speak to those advantages of why you want to do this, and ideally, being able to quantify those things and coming down to, okay, we need this many developers for this much time. There's a cost associated with that, but here's what the payoff is going to be at the back end, in terms of the cost savings or the momentum that we gained. That's one aspect, is to bring the data.

The second is around customer obsession. What's the voice of the customer here? Point to, we want to do these API things, and here are the customers that are asking us to do those things. Maybe there's an opportunity in terms of quantifying things or maybe there's just bring in the voice of the customer. What are the anecdotes? Here's large customers one, two, and three saying, "I love what you guys are doing, but I need it to be API-based, because here's what I'm trying to do and I need you to enable that for me."

A third might be pointing to the pattern recognition aspect. Point to other successful examples of, "Hey, this other part of the company or this partner that we work with, or maybe even this competitor over here that we're trying to out-compete, did this API kind of thing and it worked out well for them." That's another kind of validation that this deserves some resources.

Greg: That's where we agree. I think the biggest thing is, if you started a website, there's a bajillion tools out there for analytics and stuff like that. If you start an API, so many PMs just literally don't know who's using their API at all. So yeah, totally agree. I think being able to actually say, “yes, people are using it and here's how and here's why” is incredibly important.

When should you consider switching API service providers?

Greg: Well, if you're thinking about switching to ReadMe, do it now. If you're trying to switch from ReadMe, that's more of a 2024 thing, I think.

Josh: Ditto for Amazon API Gateway and AWS more generally. I'll come back to availability and security. So you've got your APIs, your service provider could be internal to your company, there's an on-prem thing, or it could be you're using a major cloud provider or some kind of an independent software vendor where APIs are what they do (i.e., they have an API gateway kind of functionality).

You have to consider availability and security I think first and foremost. For availability, can they support the sort of scale that you need for your API? Not only can they support it anecdotally, but do they have a published service level agreement or SLA where they have a high threshold of availability in writing that says “this is what you can count on”. And what is your recourse as a customer if they don't meet it? If there's an outage or something, what do they do? Do you get some kind of credits, or is it just a best effort, good intention with no mechanism behind it? That's one thing you have to look at. And, again, security. What's their kind of track record in terms of dealing with the threat landscape? What's their reputation as far as security goes? I think that's a big one.

Without that focus on availability and security, you don't really have a product. If you launch an API, it tips over because of traffic or there's a data breach, why do it?

Then there are features. There could be a specific hard requirement where you need this feature soon and the roadmap of your current provider is just not going to meet that. That could force you to move somewhere else and is one thing you have to look at. But then you also have to consider, all right, they support this feature that I need. Do they support all these other things that I need? And do they also have the availability and security? There's sort of this mapping of capabilities and just generally making sure that meets your needs.

And then there's obviously cost. It's going to be a hard sell to be able to say, I want to switch providers and it's double the cost or it's 10X the cost. Maybe it's worth it. You have to look at if you get what you’re paying for. But obviously cost is a factor in any business decision. And not just the cost, but what's the pricing model? How simple and intuitive is their pricing model, and how easy do they make it for you to independently estimate what you'll be paying? And is that actually going to be based on your usage, or is it truly serverless, where you pay for what you use?

Finally, the level of support. If you have a problem with them, what do you do? And do you have to pay more for extra support? Is that extra support worth paying for? That sort of support model is important, especially for enterprise kind of customers.

API Usage and Accessibility

How can API documentation best serve a diverse audience of both technical and non-technical consumers?

Greg: That's a huge thing that I really believe in and care about when it comes to who the audience is. If you said you were working on an API 10 years ago, it probably meant that you were a CS student, an engineer. And now people just want to build stuff. The coolest thing about the internet is it really enables anyone to be a creator, whether that’s tweeting on Twitter or creating TikToks, stuff like that. But a lot of people want to do something, whether for themselves or otherwise, just think of automating your house. It's not quite an API, but it's very logical the way you think through a smart home. If you're setting up your Alexa to work with your Phillips Hue bulbs, it feels very programmatic to me, where you’re giving instructions like, “at 3:00 PM, do this.“

I think the more you can do to show that not every API call has to involve writing code, the better. Zapier is one of the better companies out there when it comes to the API space, but not because they do API stuff explicitly. The word API is in their name on purpose, but they never talk about APIs outside of that. I think that's a huge one. A lot of companies have started building up components where you don't have to write the full thing, you just have to be able to copy and paste a line of code into your docs. And it has to be very bespoke. I think that's the nice thing about APIs, is that every API can vaguely be translated into an OpenAPI spec.But that's also the downside, is that people will do that and think we're done.

And OpenAPI, and this is my pet peeves about APIs, which we'll get to in a second — they should be really easy. You send out data to it and you get data back is how APIs, in theory, are supposed to work. But they're so confusing and as a developer, I'm spending eight hours trying to debug in this black box, oh, I forgot to send a JSON header or something like content type. The thing that I find exciting is remembering to really simplify it and then building layers on top of it, realizing that it has to be bespoke. I would love it if you come to ReadMe and, in one click, from Amazon, you could deploy your OAS files and be good to go and then leave.

But that's just not true. Each API is very bespoke and that's why we're so customizable. That's why you can write your own recipes and build on top of it.
I don't think there's a one size fits all solution for any API. People used to ask all the time, "Can you just magically have it all work? I don't want to write docs." And I think you really need to do everything, you can't do just docs. Showing people clicking around, generating code snippets in their language, giving them API keys where they need it, things like that are also incredibly important. But I do really think you need both. Maybe AI will come along in two years and that all is moot, but for the next few years, that's my answer.

Josh: I think it’s worth thinking about if it’s equally easy, or at least equally accessible, for both non-tech and tech audiences in terms of the documentation. Then, for a developer using your API, the theory is, it should feel familiar. There's an aspect of good naming conventions, where it's like, all right, I'm not an engineer, but I can read through your API spec and kind of get what it's trying to do, because you've done it in an intuitive way. And then there’s also a level of being consistent with the way similar APIs in the industry might operate, where you’re not doing a whole different thing. If folks are used to using a similar kind of API, your’s should be set up similarly, so that it’s kind of intuitive.

Greg: I'm going to disagree just to keep things interesting. So it's not that I actually disagree with that. Of course, everything that Josh said I 100% agree with. But I'm thinking of things from a slightly different perspective, which is I'm not necessarily creating the API, I'm working on a tool for APIs. The concept of best practices is really interesting to me, because you should follow best practices and that’s how, for an API or whatever product, there's a familiar language, whatever it happens to be, maybe it's security or name conventions, things like that.

The interesting thing, though, is that the way big breakthroughs in developer experience happen is through people really questioning the best practices. Not everyone can question best practices all the time, because then it's just a flurry of, who knows what's going on? But I do think that the biggest breakthrough is technology is someone taking a step back and saying something like, "All right, we've all been building APIs very RESTfully, is that right?" And that's how GraphQL comes along, or something like that, or whatever else.

So it's not that I think you should do it willy-nilly. You shouldn't be like, "I don't like those, I'm going to change the words and do whatever." You should definitely stick to making it feel similar and all that. But I also think it's this familiarity that puts people in a bucket and makes it so that you don't think critically about your API.

Let me put it a different way. My favorite line I've ever read in any docs is Slack's docs. And they say something to the effect of, in the first paragraph, "This is not a true RESTful HTDP API." Because everything's a post in Slack's API. They do things a little bit differently. They say, "But if you're familiar with REST, you should be able to figure out how to use your API." And what I really love about that was they didn't feel like they had to follow the way REST works to a T. They did what was best for them while being very conscious of, okay, people are familiar with certain ways of doing things and all that. I thought it was really nice that they acknowledged, “Hey, if you're looking for a pure RESTful API, this is not what you're going to get. But if you're familiar, you're going to be okay.” And I thought that was really fascinating.

What guidelines do you use for deprecating vs. maintaining old API versions? What’s the best way to smoothly sunset old versions and get users to upgrade?

Greg: Josh may have different opinions than me, as normal, in a good way. But my mindset is, that is the wrong question. I don't think you can smoothly sunset something. In the sense that people have built on it, they're relying on it, unless there's just a gigantic security breach or something like that. You're putting a lot of effort and work on other people when most of the time, you want them to use their API just as much as they want to be using their API. It's putting a lot of work on a lot of people.

I'm in favor of this concept of proxying old APIs. So you only have one version of the code running, but you keep old versions running by proxying. For example, if you change a name, if someone comes with a v1 API requests, you can do some mappings behind the scenes. I'm a big fan of being a little more creative to make sure that you never disrupt anything. The best APIs, we're still using Stripe’s from the day I built on it for the first time at ReadMe and it was 2014. I probably wrote the first code in 2013. And the API was already a little old at that point. And they've done so much since then and it hasn't broken once. And they've never asked me to upgrade or change and rewrite stuff. They've never put that extra work on me — that would've really frustrated me if they did. That takes a lot of work and a lot of effort.

I think it's the wrong question, unless you have a very legitimate reason to have to sunset things, because you're actually sun setting it and it's going away, as opposed to just renaming things. Because, to Josh's point, there's nothing wrong with saying, "Oh, we messed up with the naming conventions or we're going to redo them." But to make everyone suffer and rewrite code because of that is also really crappy. By far, the best way to do it is to find a way where you can keep them running without being beholden to the past.

Josh: I'm going to plus a million there, actually. Ideally, this is a thing that you don't do. Inertia is a powerful natural phenomenon. Changing customer behavior is hard. And asking them to do a bunch of work to move to your new API isn’t the best customer experience. It also creates a churn risk for you because it's like, "Okay, you're asking me to switch to your new version. You just opened the door for me to explore all of your competitors' versions too." So it's a risky thing to do, not just a heavy customer lift.

Ideally, as you're designing an API, you really think through, what we at Amazon would call one-way and two-way doors and putting the semantics of the request and response and the naming conventions in a way that’s stable and future-proof. The whole value of an API is, I have the API as an abstraction layer and I have all of my backend application stuff and can change it all. I can do all kinds of cool stuff and make it better. And the customer doesn't have to worry about it because they just look at the API and the API stays the same.

So, ideally you avoid sunsetting. If it's something you absolutely have to do, I think you have to communicate it really transparently. Why are we doing this? When? And what do you need to do as a customer? Ideally, give them a really easy way to do it and maybe even some incentive for moving over — like if you move by X date, you get some credits. Or, like Greg said, find a creative way, where there's a move, but they don't actually have to do anything. They can keep using the old thing and then it uses the new version behind the scenes. There can be some creativity there. And then obviously making sure the new thing works and scales and having the monitoring in place where, okay, folks have moved off. This thing's at 100%, now it’s at 0%, now it's gone, as opposed to just yanking the rug out from under people's feet.

What are your biggest pet peeves when it comes to APIs?

Josh: Well, one I just mentioned is deprecating APIs out from under people. That's obviously a pet peeve. We've touched on a few other ones, like lack of documentation, or if it's just not clear. If you have an API, but it’s not clear how to use it, or get registered and set up, or what a request or response looks like — not having that documented and easily discoverable is a pet peeve. Not having a testing environment. A sandbox or playground where folks can try it out and, if it's monetized, try before you buy, I think is important. And it'd be a pet peeve not to have. The other one we touched on was just inconsistency in naming conventions and semantics and overall making it harder for people than it needs to be. Just ease of use. Those are a couple that come to mind for me.

Greg: Mine is — I've kind of gotten to this a bit already — mine is that APIs are supposed to be really simple. You send data, you get data back. Maybe an action happens during that time. That’s really simple, and it's so easy to explain. But then, every API does everything ever so slightly differently and it drives me insane. Let’s say you want to send data to an API, that seems pretty easy, right? But there's at least five different formats you can send API data through. You can do query params, paths params, headers, body params, multi-part forms, cookies — the list goes on and on. It just drives me absolutely insane how everything else in tech is getting nicer and easier to use. And APIs still feel exactly the same as the nineties.
There's things like GraphQL and RPC that are trying to fix things and change things a little bit. But it always drives me crazy that people just believe when they're creating an API, that this confusion, these slight differences, are just how it is. And it makes something that's so simple, feel so brittle and so confusing. I'm really excited to see people realizing that REST can still be the base for how we do stuff. But also really excited people to care a little bit more about developer experience.

And everyone says they care about developer experience, but it drives me insane when you think about how many times people do things because it makes sense for them as the API creator, without thinking about how confusing it is for the end user.

It's so easy to build an API, but people make decisions based on what's easiest for them as the creator. People will generate the world's most complex OAS specs or the world's most complex docs. And then they expect us at ReadMe to take those and make them easy to use. But it's just impossible. For example, circular references make no sense when it comes to an API because an API has to be serialized. But we always have to deal with circular references, because it makes sense in the data model, where a parent might have a child, a child might have a parent, that makes sense, but you can't send all that data or receive all that data.
The tools that we have make it extra easy to do really complex things with APIs. And I would love to see people take a step back and be like, how do we simplify it? How do we make it easier? And still powerful, of course. But it's almost like that meme from Jurassic Park, where “your scientists were so preoccupied with whether or not they could, they didn’t stop to think if they should.” Everyone talks about developer experience. Everyone's always excited about developer experience. But so often I feel like people just mean they’re going to make this super complex.

And no one cares about your API at all. There's not single API I care about. There's a lot I use and I like, but there's not a single one where I get up in the morning and I'm like, "I want to go use that API." And that's not completely true, for example, OpenAI has a really cool API. But I don't want to use the API. I want to do something cool with it. I don't want to struggle with weird oddities about it and stuff like that. That's half my rant. I can go for next half hour, but we only have five more minutes.

How are customer stories and their ReadMe usage impacting what ReadMe is building next?

Greg: I definitely think that ReadMe is, while still being very similar, a very different product than it was five years ago. It's just definitely changed. People care more about different things. Before, people just wanted to render an OAS file. Now people really care. They use it as a marketing tool. The feature requests we get are just wildly different. Maybe it's because we built out the base level features, but people are really excited about things like layering realtime logs on top of our docs and five years ago that wasn't the mentality.

Five years ago the mentality, and our tagline, was “really nice docs in five minutes.” Now, no one thinks that way. Now implementations take months, because people put so much time and effort into it and really care about the end result. People really want, and this is good thing, they want to plan launches around their docs. The teams have gone from one or two users to 20, 30, 40 people using ReadMe. And that gets me really excited. The roadmap now, it's always where I wanted to be. I don't think we've ever done a pivot or changed the overall vision, but it feels like now what we're building and what people want is really converging and that gets me super excited.

What are you most excited about in your 2023 roadmap?

Josh: There's unfortunately not a ton I can say in this setting on our roadmap from an AWS perspective. We have a lot of one-on-one conversations with customers where I can get into those details. For this setting, I can just say there are some top customer asks that I'm excited about for 2023. Availability and security, like I've said multiple times, are number one for us. Even under the face of rapid growth, raising the bar continually about uptime and scalability. Bad things aren't happening from a security standpoint — security is always a weird one to talk about because it's sort of measured by the negative case and the bad things that are not happening. That attacker that was looking for a vulnerability in your API and just didn't find anything and couldn't get in. Continuing to raise the bar on both of those dimensions, along with delivering some things customers are asking for, is exciting for me.

Greg: I'm excited about a lot of stuff. We're getting more into internal microservices, so not just doing public APIs, but internal APIs as well. That gets me really excited, because it’s just as important, if not more important sometimes. Our goal for this year is to make it so that all of our docs are backed by Git, so you can write it however you want. If you're a person who doesn't want to do any engineering at all, you can use our UI. But if I wanted to automate stuff, you could Git pull or write it in Vim or wherever you want to write. I'm excited about layering GPT-4 on top of the docs, so you can ask questions. That's a little gimmicky, but I think it's also really fascinating and cool, being able to actually ask it to write code snippets for you, as opposed to having to write them yourself.

And the last thing I'm really excited about is ReadMe is going to become more of a developer hub, like a developer dashboard. We want to bring it all together, where it's not like an escape room where you're going around trying to find your API key, but instead have it all in one spot. We have a bunch of launches around that. The last thing is we're having a conference in San Francisco in April, and I'm super excited about that. That's not a roadmap thing, but it's one of my favorite things to do. Watch out for that if you want to see more ReadMe stuff, especially if you're in San Francisco and want to do it in person.