Recently, we co-hosted an AMA (Ask Me Anything) webinar with Josh Nickerson, Senior Manager of Product Management for Amazon API Gateway, and our founder & CEO, Greg Koberger. Over the course of the hour, Dave (the moderator and VP of Sales here at ReadMe) was able to ask them audience questions covering everything from the future of APIs to getting leadership buy-in on new API initiatives. Read on to find out what they said, and if you’re curious about our partnership with AWS, you can learn more about that here.

Editor’s note: Answers have been lightly edited for brevity and clarity.

Driving API Adoption

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

Josh: There's a lot to keep in mind, but availability and security are my top two concerns:

Availability: You should have an idea of how much traffic you’re expecting and be confident that you can handle it
Security: You want to be confident that you’re not opening up your systems to a potential data breach

Other potential concerns include:

What sort of authentication authorization setup do you have? Will this be an open API that anyone can use, or do you want to know the details of and set permissions for users?
How are people going to find out about the API? As you launch multiple APIs and package them into products, what scalable tools are you using to document and share them?

Greg: My biggest concern before you start: have strong use cases for why someone would use your API. People launch APIs and then nobody uses them, because the endpoints don’t make sense for real-life use cases.

Avoid the “build it and they will come” mentality — you’re asking people to dedicate resources, time, effort, and trust. Make sure there are very clear use cases that people are actually excited about and accommodate those use cases when building the API. Focus on knowing what it is that users want to build and designing your API to give them a head start on that.

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

Josh: There are a lot of key factors to take into account:

What's the input? How are they going to give you this feedback? Built-in feedback options on documentation, emails to your team, a support forum? Whatever they’ll be doing to share feedback, make it as easy as possible.
What are you going to do with that feedback when you get it? How will you prioritize issues, estimate the resources it will need to fix them, and incorporate those fixes into development sprints?

Greg: I notice that developers have a tendency to “just figure it out” and often don’t raise their hands to ask questions, which can result in developers:

Assuming that the problem/issue is their fault
Getting frustrated and moving on, writing off the product/API as a result

That self-sufficient DIY mentality is one reason docs are so important; it’s also important to actively solicit feedback to counteract it. Not just via thumbs up/down on docs, but also watching metrics for errors on specific endpoints and reaching out to users to help fix that problem. In watching for and then being proactive with with ReadMe errors, we’ve improved the documentation and fixed bugs, but also made customers happier and gathered valuable feedback.

What metrics do you look at to understand API health?

Josh: Depends on the targets you have for the API, but in general:

Engagement and growth relative to the targets you have. How many people are using it? Is that number growing?
Operational metrics like error rates. Are you seeing fatal errors? What’s the error trend-line look like? Is latency relative to where you want it to be?

Then, depending on what the API is, others can come into play from a security perspective or a monetization perspective, but those are common top ones.

Greg: It's very important to look at not just big picture graphs/metrics, but that’s not enough — it tends to fall apart when it comes to early users. Things to consider:

The sheer volume of API calls you get (in general and from heavy users) can easily skew success percentages
Looking at new customers and their usage metrics can help offset that and keep you from losing early users when they run into errors
People interact with APIs in two major ways: actual developers trying to get a response back, and in production with the API running behind the scenes
Separating those scenarios is important, something running like clockwork for a year+ is a different data set than the people making changes and trying to make something new happen (and potentially running into errors)

I agree with everything Josh said, but I want to emphasize that it's important to realize every failed API request is a real person trying to do something for real, for their customers, for themselves, etc. Make sure it's easier to highlight those very few small amounts of errors, especially with new users.

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: It’s important to recognize that cloud and serverless operation is still pretty new. The move to microservices and API-first is a newer trend — I expect that trend to continue and only get bigger from here. That trend will likely accelerate because companies get cost savings when they don’t have an in-house data center and they can decentralize things, make them more modular. That ability to move faster becomes important in times of economic shifts.

Security is big factor; the threat landscape and potential of bad actors isn’t getting any less scary. I expect emphasis on API security to continue with more scrutiny around data breaches and protection of sensitive data.

More emergence and refinement of industry-specific API standards. OpenAPI already exists, but we’re seeing open banking, open charge point protocol, fast healthcare interoperability requirements, etc. For example, there are government types of customers in public sectors where, if you're building an API in this kind of space, it needs to meet specific requirements and standards. Companies need to take compliance and regulations into account. It's important for API providers to think about how they can make it easier to manage those requirements.

Greg: It's less about this year in specific, but I’ve always thought there will be a convergence (if not a complete one) between traditionally technical/non-technical people and roles. 10 years ago, if someone said they worked on APIs, it would be a near-guarantee they’re a developer, but that’s not necessarily the case now.

The line between technical and non-technical is getting more and more blurred; people are becoming more technical just due to growing up around technology, as well as tools becoming easier and easier to use. More and more people are able to take advantage of tools that have traditionally been locked up in this highly technical knowledge.

The last thing: I’m really intrigued by companies that are realizing that developer tools don't necessarily mean users have to build everything from scratch or go for the most complex solution. Seeing more and more “choose your own adventure” type options that let users set the level of complexity to match their comfort level and goals. The best tools can meet customers at every single level based on their needs; I expect to see that more and more over the next few years and I’m looking forward to it.

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

Greg: This is a good dovetail with last answer. An example: As an engineer, OpenAPI’s API can be frustrating, because it uses prompts, which can feel unpredictable when used to standard coding methods. At the same time, it’s fascinating and interesting, and a good showcase of changing how people think about interacting with the system. Before, we’ve always interacted with systems after letting computers do most of the decision-making about how we talk, since they need specific structure.

AI flipped that, so that we’re no longer communicating on the computer’s terms. I expect this to bring more and more people into the field and make it easier to do more and more complex things. I’m excited to see what it will look like to interact with computers in 5, 10, 15 years with some of these changes/evolutions.

Josh: I've worked in Alexa AI for three years, owning internal machine learning platform that Alexa scientists and engineers used to build a different model. After that experience, I have two thoughts:

Agree with what Greg said earlier — AI and the emergence of AI will make it easier for people to build APIs
What’s happening in machine learning parallels what happened in the previous software generation, where we’re seeing machine learning ops (similar to dev ops) emerge; people want to track the evolution and lineage of a model across lifecycle from raw data to model to in production

APIs play into all of this and it’s something we need to start thinking about as we build APIs. Does this enable a machine-learning driven use-case? Does it plug into their data pipeline or machine learning ops? These are some new things to consider when thinking about business cases for an API.

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

Josh: Two things come to mind from how Amazon operates:

Being data driven: You need to understand what the ROI is, whether that’s in terms of cost, time, productivity, etc., and be able to clearly communicate that
Customer obsession: What’s the voice of the customer here? How does what you want to do with the API relate to what customers are asking for? Can you bring in direct quotes from customers to back this up?

Potential third consideration: pattern recognition. Point to other successful examples of companies that did something similar and it worked out well for them.

Greg: 100% agreed. Make sure you’re tracking metrics from the jump, so you can showcase how many people are using it and how they’re using it.

When should you consider switching API service providers?

Greg: If you're thinking about switching to ReadMe, do it now. If you're trying to switch from ReadMe, maybe that's more of a 2024 thing? 🤔

Josh: Ditto for Amazon API Gateway and AWS more generally. Aside from that, returning to availability and security:

Availability: Can they support the kind of scale you need for your API? Not just anecdotally, but do they have a published service level agreement where they specify exactly what you can expect? What’s your recourse as a customer if they don’t meet those expectations?
Security: What’s their track record in terms of dealing with the threat landscape? What’s their reputation when it comes to security?

Other things you may want to think about:

Features: Can include specific feature needs that you may not be getting at your current provider, but also making sure the feature set is well-rounded, that the roadmap includes updates that are relevant to your needs, etc.
Cost: Obviously a factor in any business decision — consider pricing model as well as total cost, whether it’s easy to understand and independently estimate your cost, whether it’s actually based on your usage or not, etc.
Support: What are the options for getting support? Is it capped at a specific number of requests per month? Do you have to pay more for extra support?

API Usage and Accessibility

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

Greg: This is very important thing to think about — people want to build things and the coolest thing about the internet is that it enables anyone to be a creator. The more you can do to show that not every API call has to involve writing code, the better. Zapier is a good example, the word API is in their name, but they never talk about APIs outside of that. A lot of other companies have built out components where you don’t have to write the full thing, you can just copy and paste one line of code into your docs.

That’s also the downside: people will do that and think they’re done. APIs should be really easy, you send data out and you get data back, but they often aren’t that easy. The thing that’s exciting is remembering that you can really simplify it and the gradually build layers on top to create a bespoke experience. Every API is very bespoke and that’s why ReadMe as a product is so customizable.

There’s not a one-size-fits-all solution for any API, but it’s not enough to just do docs. You should be showing people clicking around, generating code snippets in their language, giving them API keys when and where they need them, etc.

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: 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 documentation. For a developer using your API, it should feel familiar — it should be consistent with standard naming, formatting, etc. conventions and be consistent with the way similar APIs in your industry operate. This helps it stay intuitive.

Greg: I both agree and disagree with that, although it’s more of a different perspective than actually disagreeing. I’m not necessarily creating the API, I’m creating a tool for APIs. Best practices is an interesting concept — you should follow them, in general. But the way big breakthroughs in developer experience happen is because of people questioning the best practices. Everyone can’t question all best practices all the time, but it’s good to take a few steps back and consider whether the big-picture way you’ve been approaching things is the best way. Don’t let familiarity keep you from thinking critically about your API.

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: I think that's the wrong question — I don’t think you can smoothly sunset something. People have built on it, they’re relying on it (unless there’s a large security breach or something similar). Changing things puts a lot of effort and work on the people who have built on it already.

Instead, I’m in favor of proxying old APIs instead, where you only have one version of the code running, but keep old versions running by proxying and doing mapping behind the scenes to match new names, etc. That way, you never disrupt anything. We’re still using Stripe’s API and built on it initially in 2014, they’ve changed a lot of things since then and it’s never broken, and they’ve never asked us to upgrade or change or rewrite things. That would have been a frustrating user experience if they had.

The best way to do it is to find a way to keep the API (and its current users) running without being beholden to the past. Don’t make your users suffer and rewrite code.

Josh: I agree — ideally, you don’t do this. Changing customer behavior is hard and asking them to do a lot of work to move to your API isn’t a great customer experience. It also creates churn risk; if they have to do the work to switch to your new version, they very well may investigate all of your competitors’ versions as well.

Ideally, when building API, you think through one-way and two-way doors and create the semantics of requests, responses, naming conventions, etc. in a stable, future-proof way. The entire value of an API is as an abstraction layer, where you can improve things and the customer doesn’t have to worry because the API stays the same.

If it’s something you absolutely have to do, you need to communicate transparently. Why are you doing this? When? What do your customers need to do? Give them a really easy way to do it and maybe an incentive for moving over, like plan credits or upgrades if they move by X date. Or do what Greg said and make the changes behind the scenes. Whatever you do, make sure the new version works and scales and have monitoring in place, so you can see when users have moved off and phase out slowly, instead of yanking the rug out from under the users.

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

Josh: I just mentioned deprecating APIs out from under people, that’s a big pet peeve of mine, but aside from that:

We’ve also touched on lack of documentation or unclear documentation and how that affects users — that's another one of my pet peeves
When it’s not clear how to use an API, get registered and set up with it, what a request or response looks like
No testing environment — it's important to have a sandbox where people can try it and (if monetized) try before they buy
Inconsistency in naming conventions and semantics

Greg: APIs are supposed to be really simple: you send data, you get data back, maybe an action happens during that time…but every API does things slightly differently. Everything else in tech is getting easier and nicer to use, but APIs still feel exactly the same as they did in the 90s.

People just believe that when they’re creating an API that the confusion and slight differences are the way it has to be, which makes something that should be simple be confusing. I’m really excited for people to care more about developer experience; people will say they do, but then do things because it makes sense for them as the API creator, without thinking about end users.

I’d love to see people take a step back and ask themselves how to simplify it, make it easier. People make their APIs super complex and forget that nobody cares about your API — they care about what cool things they can do with it.

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

Greg: ReadMe is a very different product than it was five years ago, people care more about different things. Before, people just wanted to render an OAS file. Now, people are using their documentation as a marketing tool. We get different feature requests. People are really excited about things like layering realtime logs on top of 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. Implementations take months, because people put so much time and effort into it. People want to plan launches around their docs. Teams have gone from 1-2 users to 20-40 people using ReadMe. I’m really excited about current roadmap; it feels like now what we're building and what people want is converging.

What are you most excited about in your 2023 roadmap?

Josh: There's not a lot I can share in this setting, but I can say there are top customer asks for 2023:

Returning to availability and security, they’re the number one priorities
Even under the face of rapid growth, constantly raising the bar for uptime and scalability
Security can be weird to talk about because it's measured by the negative case and the bad things that aren’t happening, but doing well on that front
Continuing to improve both of those things, along with delivering some new things customers are asking for

Greg: There are lots of exciting things coming up:

Getting more into internal microservices — not just doing public APIs, but internal APIs as well, which can be just as (if not more) important
Our goal for this year is to make it so that all of our docs are backed by Git, so you can write and automate the process however you want
I'm excited about layering GPT-4 on top of the docs, so you can ask questions, which may be a little gimmicky, but is also really fascinating — being able to actually ask it to write code snippets for you, as opposed to having to write them yourself

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 and have it all in one spot; lots of upcoming launches around that. Other than that, we're having a conference in San Francisco in May —not a roadmap thing, but 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!

That's all, folks!

We hope you enjoyed reading Greg and Josh’s thoughts — we certainly enjoyed hearing them! If you’d like to read the full transcript, you can do that here. And if you want to learn more about what ReadMe can do for your team, take a look at our customer stories, or sign up for a free trial here.