James Higgenbotham, LaunchAny

All right, here we are for Breaking Changes episode two, and I have my friend James Higginbotham with us. So James, to kind of set the stage for what we’re going to be talking about this week: he is the enterprise-grade source of knowledge when it comes to APIs, the API lifecycle, that I always turn to, and many of my customers and clients over the years have turned to. So with that said, welcome James to Breaking Changes. Thanks for coming on.

Yeah, thanks for having me, Kin. I’m excited to be here.

So you’re an independent professional. Last week we talked with Shutterstock. I wanted to kind of shift it up, because I find you have a very valuable lens on the space that I think our customers need to hear from, and you provide some interesting view on the problems that most of our enterprise customers face. So you’re an independent professional. Why remain independent? Why not join an Accenture, a big agency, or another firm? Why do you do this on your own?

Well, there’s a few reasons. One, my career path has led me down this trajectory where I’ve spent time in software architecture and product thinking, and this intersection with APIs is a great blend between those. The other is that when I first started out, there were not a lot of organizations that had API-specific practices. I’ve been consulting for years, I know what it’s like to be a consultant in a larger organization, and you really need the support system of that organization to be able to make a really good go of it. So there wasn’t really anything out there. I jumped out on my own, and I’ve just been having a blast ever since.

Nice. So how do customers hear about you? How do you find new customers? What’s the general way they find your way?

A lot of times it’s organizations that we previously engaged with. As they reach executive or director levels, typically they’ll start talking with others in the industry, and we’ll get a referral from there, or from the API community. So those like yourself and others that are heavily involved in the API community, whether they’re full-time at an organization in that capacity or if they’re like me and they’re consulting independently. Every once in a while we get a contact form on the website where someone will just find us organically when they’re looking around for some information, but most of the time it’s through referrals, and it keeps us pretty busy.

Yeah, I definitely have sent a few folks your way that I know need your help. So when it comes to what you do, is it more technical or is it more business?

It’s a blend of both, really. I come from a technical background. I’ve been a software developer, software architect, in a consulting capacity, so I’ve worked with a variety of different verticals over my career. But a lot of times what I’m involved with is a blend of the two. I need to be able to sit down with executives, from the CIO to the CTO, and understand kind of where they’re at when I’m first starting an engagement, or when we’re in the sales process, and then we work with their offices to help deliver the services and deliver the API program. So it takes a blend of both: understanding what it means to deliver an API program from a business perspective—what are the metrics, what are the key goals from the business side of things—as well as the technical side, helping to advise on processes, standards, patterns, those kinds of elements, and working with those that are in the trenches delivering APIs to help them start thinking about their APIs in new and innovative ways.

So in your usual engagements, what does a customer walk away with after working with you?

A lot of times the organizations we work with, they already have an API program in place. It may be formalized or may not be formalized as of yet, but they’re producing APIs and they’re seeing an opportunity in one way or another. Either they’re wanting a little bit more formality around their program and their processes, or maybe they have some of that and they’re looking to mature and grow it or scale it across the organization. So when we’re done working with our customers, they’re going to come away with a few things. One is that they’re going to shift their mindset from more of a data-driven or app-driven API perspective, and they’re going to start thinking more about outcome-driven APIs. What are the users and the developers trying to achieve? What kind of result are they trying to produce? That’s the big one.

The other thing we’re going to look for and try to instill in these organizations is a sense of API ownership. Many of the organizations we work with, they will treat an API like they treat any other initiative in the organization. It gets funded as a project, it has a lifecycle, it has a natural end date, and then the API is just going to sit out there and not be improved and matured. We want to make that shift for them, so that they have more of an appreciation for owning that API and growing it over time like any other product, whether they’re a SaaS or whether they’re just delivering APIs for their partners and workforce.

The last thing is just an appreciation for great API documentation. That’s a discipline that’s really lacking, and we try to instill a sense of making sure that we have great documentation for the APIs that we deliver, and making sure that we have the technical writers in place to help support them, so the developers don’t feel like they’re left on their own. That way we can ensure that these APIs deliver a great developer experience.

Yeah, I’ve always felt like you help customers realize that this is a journey, that this is an ongoing thing. That’s why I always felt like sending people your way was always a good thing, because most of the people I was talking to just didn’t quite realize that this is an ongoing thing, that it wasn’t just something they’re going to be done with. The type of attention that you give really helps them in that journey and equips them for the long haul, not just the quick fix or some of the more trendy advice people get in the space.

I’ve known you for quite a few years now, and one of the things I really like talking with you about is the history of APIs. You’re one of those people—I don’t want to call us old-timers, but we’ve been in the space for a while. So I want my audience to hear a little bit about that history and your view of how we got here. When did you first see the potential of APIs?

Well, if we really go back a while, I got introduced to distributed computing and some of those ideas in probably the late ’90s, when we started seeing network computing really take off. We had had mainframes before—I wasn’t really as involved during that time frame—but just seeing, even just from the Java perspective, the need to be able to push data around the network and access systems across the network, and really start to see what became more of a cloud architecture that we have today. It was just kind of the seeds of that then. But really it was probably about a decade ago where I really started seeing this vision of what network APIs could become. I was heavily involved in service-oriented architecture, SOA, SOAP, done CORBA before that, a lot of different technologies. And as you said earlier, these technologies change but the principles stay the same. So as we started seeing a lot of these mobile devices come out, that’s when I really started to see how APIs are really becoming first-class—not just a technical solution but really a blend of business, product, and tech. That’s what really got me excited about it.

But my history goes back quite a ways now, and it’s been useful because sometimes we see the same patterns repeating over and over again. Sometimes the same principles apply today that applied in the ’90s, and then sometimes we have to make adjustments, we have to learn from our mistakes. So I really like to instill a sense of history whenever I teach and take people through training. We don’t dwell on it a lot, but just kind of stepping back a little bit and asking ourselves how did we get here and why, what can we learn from that, is really important. It helps us to move forward in a more productive and innovative fashion. We don’t repeat the same mistakes, but we learn from them and move on, and we can try different things along the way.

Very important, because it’s definitely one of the reasons I started telling people to tune into your work. I was getting those questions: didn’t we just do this? This is 2012, 2013, and I think people had just kind of recovered from SOA investment, into service-oriented architecture, and this API trend came along, and they would ask, didn’t we just do this, what’s different? And I didn’t always have the right answer, so I always felt like you were a source of information that I could send folks to, to help out with that.

Yeah, I appreciate that. For me, I think it was really eye-opening when I started to see APIs productized. We had the classic Twilios and the other examples, but I think for me the big aha moment was when I was working with Heroku, as a platform-as-a-service when they first started coming out. At the time I was consulting to a number of startups during that season. It was more about startups and enterprises for a moment in time, and they were using Heroku to deploy out. Heroku has always had this marketplace where you could install add-ons into your application. For those that may not be familiar with Heroku, you take your code base and you provision a project on their infrastructure, and you just do a git push of the code, and it would auto-detect what language, what framework, how things should be set up. It just configures it and deploys it and you don’t have to worry about it. It’s kind of the ultimate idea of, I can write code and get it deployed and not worry about standing up infrastructure. It was really popular for startups. You start deploying your product, and all of a sudden you go, oh, I can add in a database, and you flip a switch or run a command line and the database is enabled. And you say, I want email, what can I use? At that time it was SendGrid that was kind of the one really leading in the Heroku marketplace. And you start to realize, oh, I’m really using APIs to send emails. I don’t have to write SMTP clients and submit data that way. Although I could send emails that way, I could also use different kinds of APIs they offered, and I can enable that API really quick with their marketplace.

It sort of gave me the big aha moment that this is much bigger than the SOA world, much bigger than all the technologies we had before, because we had the SaaS solutions out, and now the SaaS solutions were starting to create marketplaces, and the power just started to really exponentially grow for a developer—what they could do and how they could pull things together quickly and easily. That really led me to the current incarnation of APIs and really got me excited about it, because we’re not just sitting down and training people how to use a particular technology—here’s how you do your SOAP service and so on and so forth. It was really about how do we turn this thing into something that’s meaningful for the organization, whether it’s a product, whether it’s just running revenue through it, whether it’s enabling our workforce to be more efficient, whatever it is. It was a lot more powerful than it was before, and the story was starting to really mature, and that really got me excited. It was fun times.

Yeah, and I think that public aspect is why I find a lot of people are waking up. They’re using more SaaS services, they’re using more cloud services, as well as that core internal infrastructure that’s so represented. It’s a much different world than it was earlier on when SOA was taking root. So for these enterprise organizations that we’re talking to, everyone’s waking up to the fact that they need APIs, but they’re using an increased amount of third-party ones. Where do they start? What’s the first thing an enterprise organization can do that’s going to have the most meaningful impact when it comes to doing APIs?

The starting point can vary from org to org, but really what I like to do is sit down and try to help them establish a Center for Enablement, or C4E. It creates consistency, and it creates a program where we coach teams and support teams that are building APIs. One of the most frequent things we encounter is that teams themselves, when left on their own, they’ll figure out how to build an API, but how to be effective at it is something completely different. So being able to spend a little time with the organization to help them formalize their program and grow it is really important.

Now, the C4E is made up of a lot of different elements—we’ll probably get into it as we talk throughout this discussion—and it has challenges, but really more than anything else, the goal of the C4E is to deliver a group of dedicated experts that can support the teams in the organization. It’s much different than the old SOA governance days where we had these kind of ivory-tower situations where everyone controlled everything. It’s more about having experts that understand how to design APIs and capture patterns and create consistency in the developer experience. That’s what you really need, and so that Center for Enablement’s a great place to start. It will have the biggest impact, because it’s going to help teams be more effective and give them the support that they need. When they have a question, they have a place to go to. When they’re not sure what kind of decisions to make, if they have multiple choices, they know where to go. If they’re just kind of feeling a little uncertain about what they’re going to release, that Center for Enablement’s there to help support it. And they do it through a number of different disciplines and standards, practices, patterns, and so on. But that’s where we like to start, and that sets the stage for everything else, because they’re the ones that are going to be front line.

Yeah. Is this something that would you say is a bottom-up movement, or is it something that should be done from top down, or is it a mix of both?

I do see organizations try to start kind of from the bottom up and get their API program going, and they can usually get it to a certain point, but it really does require buy-in from the top down. So you need your executives to be able to fund this for longevity of the program. If you don’t have the funding, it will always get deprioritized in favor of something else. If you have the executives on board, you’re going to be able to move forward effectively. So you can start it as maybe a skunkworks project, or maybe just one team says, here’s some lessons we learned, and they throw it out on a wiki or something internally and share that with other teams. I’ve seen that be effective to a point, and that is usually a nice incubator for the C4E if you don’t have executive buy-in. But there will be a point where you’re going to have to have that buy-in. The organizations that have it flourish with their API programs, the ones that don’t really struggle. And the ones that don’t have executive buy-in have struggles bringing us in as consultants, because they can’t legitimize the spend necessary and the effort necessary to get all those elements in place so that they can multiply their effectiveness out to the edges of the organization, to all the teams that are executing, unless they have that executive leadership.

Yeah, it makes sense. It reflects a lot of the conversations I’m having with organizations: most leadership waking up to the fact that they need to get a handle on the APIs. And I would say the number one reason that leadership’s waking up and asking for, when it comes to APIs, is API governance. It’s something that isn’t always positively seen from a bottom up, but from a top down they want more API governance, more governance across operations. So for leadership watching this show, what is API governance?

Sure. API governance does definitely come with a negative connotation sometimes, particularly for those who were around during the SOA days and they established an SOA governance board. That oftentimes brings you back to the days when everything was very centralized, there’s a small group of people making a lot of approval decisions for the entire organization. Today API governance looks a lot different, at least in our perspective. The C4E that I mentioned earlier is a great start. It’s a group of people that are experts, and part of what they’re going to do is they’re not going to dictate down from on high, thou shall do this and thou shall not do that. They really instead want to build a series of guide rails to help the whole organization be efficient and effective at using APIs. So we want to give them the room to allow the teams to develop that API the way they need it to, but we also want to recognize that there are some better ways to create consistency across APIs.

Some organizations have been producing APIs for years, and if you go look at one API, it’ll look completely different than another API in an organization that were designed relatively in the same time frame—not even allowing calendar time to tick away, but just two teams building two APIs in parallel for two different purposes. They’ll look completely different. It won’t even look like it’s from the same organization. And sometimes that’s okay, when we’re targeting different audiences, different market segments, they may need different things. But oftentimes we want to allow our developers that are going to be using their APIs—whether they’re internal, partners, or customers—to use them in a consistent way. So when they start blending those APIs together to do new and interesting things, they’re not relearning a whole new way of doing something.

So in that case API governance is really meant to make all of that a reality. And we do that in our world, in the world of LaunchAny, through the API Strategy Compass. When we engage organizations, we help them understand there’s really eight core disciplines that you need to have, and when you have those eight disciplines to some extent along the way, then you’re going to have more consistency, a better developer experience, more reuse internally, and more opportunities to capitalize on market shifts as they occur, and you can respond to them quicker. A lot of that compass, it’s driven by—just imagine an eight-point compass. We start on the true north with strategy and culture. Is your strategy clear? Do you know why you have an API, and is it driving growth for the business in some way? And then we start working away clockwise around the compass. So we look at process and governance—so we do have a little bit of governance in that you may want to have a bit of consistency, style guides and things that can be enforced with tools or other means. So you want that in there, but you want it to be lightweight, you just want guard rails, just something that keeps people kind of headed in the same direction so we don’t have APIs scattered with all sorts of different things, but nothing too complex or overreaching, I should say.

We also look at the portfolio: what kind of portfolio and products are you designing? What are your digital capabilities that you’re producing—the APIs, the events, the streams, those things that represent what your business does, your business capabilities in digital form? And how are you organizing that, and how are you making sure they’re aligned? We then look at discovery and documentation. So as a developer, how do I find the APIs? Is the documentation supporting that discovery? We then look at onboarding and adoption. Are we making it easy for developers to get started? Is it low friction? How do we help developers be effective at what they’re doing by using the APIs? Otherwise the developer’s going to go straight back to that database that they’ve always gone to and start running SQL queries, and they’ll bypass the API if they’re able to. So we need to make it low friction, so that the incentives are there to make sure that we can get those developers on board quickly.

We look at design and delivery: how are we consistently designing our APIs and delivering them, making sure that we have that right lifecycle in there. And then we look at management and analytics: are the APIs owned, do we have metrics that we’re tracking, are they helping us move in the right direction? And then finally all of that is wrapped up with security and operations: how do we secure the API so that we don’t open up different kinds of attack vectors through our API, and then how do we make sure that the operations support highly available and resilient services? So we look at all of those things, and all those go into the C4E, into that process, they fit into that API governance, and that helps make a healthy ecosystem. And you can start small and work your way up. You don’t have to do all of that at once, but it’s really important. So you can see where that Center for Enablement and having those experts and that support for those teams that are delivering is really important. Not every team’s got to go through this checklist, but if you have that C4E group and API coaches that can jump in with the API teams and help them deliver effectively, it makes a huge difference, because now they’re supported, now they can focus on what they need to deliver, they don’t have to reinvent everything from scratch. And we have more consistency in the way that we manage those APIs inside the organization and how we offer them outward to our partners and our customers.

Well, it’s a much more holistic view of the landscape than I would say the API governance a lot of you get, which is a very narrow focus on design and maybe validating that design and getting consistent design. But you have a much more holistic—the strategy and culture, the process and governance, applying it to the products in the portfolio that’s in place. But I would say the most visible aspect of the API lifecycle, which is kind of what people point to as one of the number one pain points, is documentation. It’s kind of the poster child for what’s wrong with APIs or what’s deficient. Why do enterprise organizations struggle so much with documentation?

Yeah, you’re going to get me on my soapbox a little bit here, Kin, because this frustrates me as well. If you’re a developer that’s listening to this, you probably have experienced a really bad API, whether it’s a web API or just a library for your programming language you’re trying to use, and you have to dig into the code to figure out what’s going on. It gets really frustrating. If you’re an executive, you’re a leader, you probably have encountered situations where the project’s behind, you can’t figure out why, and it’s because we thought that a particular API could do something, we made some assumptions about it, the documentation maybe was a little thin or a little vague, and we’re not really sure, we couldn’t try the API out soon enough to vet and mitigate those risks that were there. So here we are now trying to deal with that real time when we’re trying to execute, and it can be difficult.

But I personally, from my soapbox perspective, think our software industry has really failed with documentation. I think we failed with documentation as part of being done with software. We’ve either assumed that the developer’s going to be around forever and we’re not going to lose that knowledge of how the software works, or we’ve confused code and documentation. Sometimes we encounter people that mistakenly confuse code as documentation, and while code can tell us what the execution path is or what the intention is, it doesn’t tell us why. The code never tells us why it was built unless we have documentation. So at the simplest level of code, without even talking about web APIs, we failed. We failed because we’ve allowed the code-as-documentation to win in some organizations, and it creates problems.

I was always taught you write the docs before writing the code. And I think it was Steve McConnell from his Microsoft Press book line—maybe it was the Pragmatic Programmers, or maybe it was both of them—kind of talked about how to write the documentation for a function or a method before you actually write the code. Make sure your logic is sound, make sure you explain why you’re having to do this, what the purpose of it is, not just at the method level but internally as well. Because the next developer, even if it’s you six months later, won’t know what’s going on, and you’ll want to lean on that. And if you can document it, then you can write the code. But if you can’t document it, then it’s going to be a little bit harder to express both the intent and the reasoning for the code and get the code right the way that you want it. So this leads to confusion. Poor documentation makes it harder on developers just working on a single code base.

Now if we extract that out and we look at our web API surface areas that we’re offering, then the poor documentation or lack of documentation just amplifies, because now we’re not targeting a specific small set of developers that have to work with some code, a small little part of an overall code base. We’re talking about tens to hundreds to thousands to tens of thousands of developers that are going to be trying to use a particular API, and they’re not going to know how to do it. So they’re either going to walk away, or they’re going to just completely pound the developers with questions, and those developers are going to be overwhelmed and unable to support that API at scale.

So we have to think about a few things. One, with our web APIs, we’re never going to be able to see the source code. If you’re interning for the organization and you’re using another internal API, maybe you have access to the source code by virtue of your single sign-on with your org, but you may not even know what repo to look at. But most organizations are not going to release their source code externally. Twitter is not going to share their source code for their API so you can dig in and understand what it means to use it. Neither is Slack, neither is Stripe or any of these other organizations. So you’re not going to have the source code. We have to focus on great documentation, and that documentation has to meet developers where they’re at, whether they’re a new developer and they don’t understand certain patterns and practices, or they’re the expert and they just want to dive in. It has to meet them exactly where they’re at.

So if we get code-as-docs wrong, then our API docs are going to suffer as well. If we get the idea that documentation is part of being done—not just the code, not just the tests—then we’re not going to struggle as much, then we’re going to deliver a great experience for the developers, and the result is going to be more effective developers that are able to use APIs quickly and easily and get things done. That’s really where we want these programs to be at, not struggling to even figure out how to use one API. Organizations I work with that don’t have this documentation effort down—maybe they don’t have internal tech writers that can help craft that documentation but coach developers to being better at it, or kind of filling in the gaps from developers, taking that handoff and taking that extra mile—if they don’t have that, then most of the time they either have multiple copies of the same API, which is unnecessary, or no one’s really using APIs at all, and they’re just duplicating data, replicating it to another database and running SQL queries, and they’re not leveraging the opportunities that APIs bring forward.

Yeah, so important. Just forcing folks to get out of their current mindset and think with that external focus. And I think a lot of people are already on this journey. In a lot of organizations we see a lot of API-first, design-first movements. But for folks who are trying to move this needle forward, there’s a lot of entrenched folks who are believing code-first, code is how you do it, that’s what they are, they’re developers, they’ve been writing code for years. So what sort of advice do you recommend for getting these code-first folks to think more externally and think about the design of the APIs that’ll lead to these better outcomes?

Yeah, it’s a bit of a challenge. It’s why our northern compass point is strategy and culture, because it requires buy-in from the organization to accept that the role of the developer’s changing. I hear the term all the time, shift left, shift left, shift everything left, shift security left, shift automation of test automation left, shift API design left. Pretty soon, if we shift everything left, there’s nothing on the right. The poor developers are getting just overwhelmed with things to do. So you do have to shift the culture, and you have to say it’s okay to take an extra beat and slow down and think about the design. It might mean that the organizations need to rethink how they approach their API design, and to make sure that you have that C4E there where people can raise their hand and say, I need a little help.

I’ve heard it time and again: API first, this is what we’re supposed to be doing, don’t know what that means. To me, I’m a developer, I’ve got a year and a half worth of experience out of university, how do I move forward, how do I do this? I’m not an architectural thinker, how do I figure out how to design an API? So first and foremost, there’s nothing wrong with code-first if you’re using that to explore the problem space, but at some point you have to step back and really reassess what you’re trying to do and take an outside-in perspective. Sometimes that requires having API coaches, API architects that are working with the team shoulder to shoulder and helping them surface and get through those design issues and help them think more about design and make that more of a first-class process.

We do that at LaunchAny through trying to teach organizations how to think about outcome-based API design, and we make it really easy. We use a process we call Align, Define, Design. We align first on understanding what we need to build. There is nothing more frustrating as a developer—and I’ve experienced this, and I’m sure those of you that are listening and watching now that are developers or have done development in the past have struggled with that as well—there is nothing more frustrating than writing code that never makes it into production. It gets thrown away, it gets abandoned, or it gets torn apart at the last minute because we completely misunderstood what was needed, and now we’re under the gun to deliver what’s actually needed. That was the intent of agile, to have constant communication channels between the business, the customers, and the developers, so that we’re all kind of aligned. And we’ve somehow forgotten that with some of the agile methodologies we have out there, or we’ve delegated that to product owners and product managers, but we don’t incorporate them into the API design.

It’s often seen—APIs are often seen as a technical concern—but it’s not like we’re choosing whether we’re going to use Node or Java and Spring Boot or something else completely. It’s really more about how do we blend our business and our technology together. That’s where the align phase is. We all come together and understand a little bit more about what we’re trying to do, what the outcomes are. We allow the voice of the customer to bubble up, and this becomes more of a product ownership, product thinking mentality than we’ve had traditionally in IT or in software product development of any kind. So that aligning is essential. It gets everybody on the same page.

Then once we have that, then we teach people to take those artifacts and those things that come out of it—job stories or user stories and other elements, event storming and other kinds of things to do during the align phase—and turn those into high-level API profiles. That’s the defined phase. We define what the APIs are and what operations they need to deliver, but we do it in a protocol-agnostic way. We don’t get specific about what it needs to look like. Then, once we define what the API needs to look like, we can go into the design phase. And these are all kind of rapid-fire, they can happen over hours or days depending on the scope of the effort. We go into the design phase and we say, do we want to use a REST-based style, do we use GraphQL, do we use gRPC, what makes the most sense? And then we design that API to meet that need. And we might actually design that API in multiple ways. We might deliver a REST-based API and a GraphQL, because our target audience is maybe split on which one they prefer, so we need to deliver both. So we may deliver one first to meet the needs of a particular audience and then follow it up with the same API definition realized as a new design with a new protocol, maybe gRPC, GraphQL, whatever it is, and then we extend that further.

Once we have the design, we can go into the delivery phase, and that’s where everybody can parallelize out the work. We can build the API, we can build automated tests, we can document it, we can build mocks for it, we can go through all those different elements, and we can do it in parallel, so that the API is now not a blocker. We’ve all come together, we’ve aligned and defined and designed, and now we can go off and do the work that needs to be done to deliver it and to manage it once it’s in production and to own it. And we repeat that frequently, we iterate that frequently, as we learn more, need to expand the capabilities of the API and do more and more work. And along the way we’re checking in with our customers where we have artifacts we can share with them. You don’t want to share your code generally, so starting code-first doesn’t give you anything to share. But having a design helps everybody come to the table, bring their skills, their insights, their domain expertise together to solve the problem at hand, make sure we’re all aligned on the same thing. Define the API, design it, and then we can share that artifact, usually an API like an OpenAPI specification format or API Blueprint or something else.

So it really makes a huge difference. In fact, I’ve documented this in an upcoming book that I’m releasing from Addison-Wesley. It’s called Principles of Web API Design. I think there’s pre-order on Amazon and on the Addison-Wesley InformIT website and some of the others, where I walk you through that step by step, so that individuals or teams can understand how to do that. But we actually train on how to do that at scale for organizations. We’ll train small amounts of teams and then we’ll scale that out, and it makes a huge difference in how teams approach their API designs. It helps them go code-first when they need to, to explore a problem, to de-risk something, to figure out what’s possible, and then we can step back and take that outcome-based approach, and we have confidence that our API design is going to be meeting the needs of our customers, not just our own internal needs to get data out of the database and send it across the wire.

Yeah, wow, that’s so much more holistic than I think people think about. The design needs within an enterprise operation is much more aligned to the business needs, the goals, it focuses on the humans. It’s not—I think a lot of the classic API design is part of governance conversations I’m seeing. So that’s definitely something as far as how organizations can move forward, can think differently about their operations. But when you get that in motion, it’s going to take understanding and kind of dialing it in. So what are some meaningful metrics that teams can tune into when it comes to their operations to understand whether they’re succeeding or failing once they have this in motion?

Yeah, metrics are a challenging thing. I like to get organizations to start off by saying, what is success for this API? Is it the number of queries sent to it? Is it a particular transaction or outcome, maybe multiple steps? So for an e-commerce example, if we’re shopping, adding things to a cart is nice, it gives us some insights, but the sale is really the big one. Completing that transaction is sort of the desired outcome. So do we have a way to track and determine what our conversion rate is? It’s a lot like managing a website, in that you have that funnel, and you’re going to have people coming through the funnel, they just happen to be using an API instead, and then eventually they’re going to come out and hit a particular transaction or key metric. That’s the first thing: what is it that this API does that we want to track? The number of something—number of successful transactions, number of queries, number of whatever it is. That’s the first metric.

The other one to look at sometimes is number of consumers. Are we seeing growth in the API, are we seeing adoption? That’s not always a great metric, and it might need to shift a little bit. Maybe the transactions or the successful outcomes, maybe that’s the primary metric you drive on. It could be number of consumers if you’re building kind of a shared API, particularly within an organization but even outside of it. And then looking at things like the response codes. Are we having error messages sent back to the API? Is it because there’s some sort of UX issue, the form is not understandable, so they’re filling out bad data and the API is giving back an error message and the user’s having to correct it? Can we optimize that path? So there’s some secondary ones like that we’re looking for, the 400-style error messages where there’s some kind of problem going on underneath, instead of the 200s. And then the error messages where the servers have failed, like the 500s—is there instability in the code or infrastructure we need to improve?

One of the things that I thought was a really interesting story: we had one client who had offered an internal API. They had another team starting to consume it. They were doing it in kind of a staged fashion, in a staging or pre-production environment, they were using the API and everything was fine. They rolled out the code, the app, into production that was using that API, and all of a sudden they started tracking usage of an API and they started seeing a spike in the number of requests per second for a particular API. They narrowed it down to the API key for that team, and they looked and figured out that the team was not using cache control to save themselves hitting the API. So every time they needed a piece of data, they weren’t keeping it close at hand, they would use it and then throw it away. And what was happening is they were actually doing that inside of a loop—inside of a for loop, they were making a bunch of API calls unnecessarily, for sometimes the same amount of data. So having some metrics that both determine your outcome and also determine how people are using your API will go a long way, and it doesn’t have to be a lot of them, it just has to be the right ones. And sometimes it can take experimentation.

But also looking at APIs that maybe were built and put into a catalog and were only used by one consumer—it ended up being kind of a one-to-one relationship—and asking ourselves, what are those APIs that have no consumers? It was built and no one ever used it, or it’s built and just one team’s using it. How can we improve that reuse? That sometimes takes a little time to finesse, but having metrics like that to identify those things that we’ve built and have infrastructure running for that no one’s using—those types of metrics are really useful as well. They can tune the operations of your API portfolio and allow you to refocus your efforts somewhere else and refocus your infrastructure dollars somewhere else as well.

So most of these metrics you’re talking about are going to be found at the API management layer, which is pretty central for most enterprise organizations. In your experience, is this usually a centralized API management, one gateway, or do you see more federated and distributed approaches to the API gateways?

I see a combination, both with the API management layer tooling as well as how the governance is spread out and how that kind of reflects in the API management layer. So oftentimes what we’ll see is a shared group that’s responsible for and understands how to configure and secure and monitor and manage the API management layer, and that’ll be a central group that kind of keeps things small and lean. But they may have multiple instances of the API management layers, and that may reflect either the way the organization is structured—kind of Conway’s law of how things emerge—and every team may be needing an API management layer for a particular API they’re externalizing to a group of partners, and they don’t want to have that partner negatively impacted by a problem from another partner. It’s kind of the classic multi-tenant problem in the SaaS world as well.

So we’ll see some sort of centralized group that oversees the API management layer. We’ll sometimes see, prior to an organized C4E, teams where they don’t know where to go, they don’t know how to find out who else is using API management layers or building APIs themselves, and they’ll just kind of stand up their own thing, or they’ll build their own inside of code. So it takes a while to figure out how to manage those, because they’re scattered all over the place. It creates a lot of inconsistency in the developer experience, because the way that I go get an API token for one API will be different than another API inside the same organization, and that can be pretty frustrating. So having some sort of centralized way of provisioning an API management layer gateway for your particular team or a group is really important. And then over time it usually gets distributed and scales out. So you might have different API gateways or management layers implemented across the organization.

Some of the newer ones are really coming out and offering some great features, where they’ll allow you to have many instances but be able to submit a specific configuration and say what group, cluster, or instances they go to, and then they’ll aggregate a lot of these metrics back together, so that you can get a snapshot of the entire organization as well as the teams can get snapshots of their own APIs if they own them. Likewise, those API management layers reflect oftentimes the governance requirements as well. Sometimes you have PCI compliance or other regulatory requirements, and so you have to segment out some number of instances to protect those teams and those particular assets to improve the auditability of certain systems, without having to audit the entire infrastructure. You can segment it and manage it separately.

So there’s a lot to that, and that sometimes will result in having different federated or distributed approaches to your API management. Your C4E—you need coaches that understand some of the regulatory requirements that a particular team has to go through and factor that into the API design. Having one C4E that has to know the entire organization is very difficult, so sometimes that actually introduces some complexity, but a lot more power and scalability when it comes to the governance side of things, or the C4E side of things as well. And sometimes those map one-to-one with how your API management layer instances are deployed, sometimes it doesn’t. It just varies.

I think that was the most nuanced API management response I’ve heard, as far as how it maps to the overall organization, rather than, oh, it’s just something you need, do it. It was actually decoupling the reasons why, not just doing it. So there’s a lot going on there potentially, a lot of things being measured, a lot of information coming out of that. What should leadership think about when it comes to reporting upwards, to keep them informed of what’s going on? What’s the most meaningful out of all of that?

Yeah, I think there needs to be—if you can create a one-pager for executives. So what’s the health of our API program? Did we have any significant outages? Do we have APIs that we’re seeing trending upward and being used heavily? Do we have APIs that are trending downward for some reason, or experiencing a high number of error rates, these different elements that your executives care about? Of course, the highest-level executives sort of want the green, yellow, red, and maybe a little bit of narrative for it. The mid-level managers need to dig in and see the details, because they may need to go back to a particular team or part of the organization and say, hey, we’re having an issue here, what’s going on with the quality of the API, what’s going on with the quality of the code, why are we having a spike in errors or something else? Or, we’re seeing more infrastructure usage here, because we’re seeing an uptick in the API—what does that mean, do we need to optimize, do we need to make things more effective? So rolling that up is really important.

The other thing that we’ve seen that really works well for large organizations is viewing your API portfolio as a series of capability domains. Like in the hospitality world, we might be concerned about booking, making reservations, the booking process, and that particular area requires a set of knowledge that others in the organization may not have. So being able to coordinate and manage and report upward what’s the health of the booking area, what’s the health of the check-in process, or in an e-commerce world, what’s the health of the shopping process, what’s the health of the adoption of our third-party partner APIs, what’s our conversion rates going up and down—all of those different elements have their own metrics, apart from some of those general ones I shared earlier. And those reporting structures, both as the teams that oversee and design and manage and deliver all those APIs, as well as the reports that determine the health of it and allow those things to be bubbled upward, are oftentimes benefited from being grouped into domain areas, capability domains.

So that in turn requires a little bit more of a product perspective, because now we have these different capability domains, and now we need product owners for them, and there’s going to be roadmaps for them, and they may be organized by business unit or maybe organized by other types of organizational structures. But however you do it, being able to dig in and say where is the problem—we need to be able to have those experts. So we see that a lot of times enterprises will come in and they’ll be like a search team, and they’re really good at search, and they have to be good at search across a bunch of domains, but you go to that search API or the series of search APIs and you can find what you’re looking for, and then through hypermedia links or other kinds of ways we can go to that specific capability once we find that search result, we know where to go to get more details about it. Others might group it by, like I mentioned earlier, more functional, and you may take something like a booking and break that down into smaller discrete units that are really good at bundling up data and sending it to partners to allow other partners to resell your vacancies and different properties for your hotels or for your airline, whatever it is. So there’s all sorts of different ways to do it. But being able to break that apart and think about the topology of your API program as a whole, and knowing that certain areas, certain APIs will use different metrics, will need different reporting structures, ones that you react to differently, will need different skills and subject matter experts, is really, really important.

Yeah, it all just keeps coming back to the business objectives and goals for doing this. It’s not just tech for the sake of tech. So I love how all roads kind of end up like that as part of your strategy. So to kind of wind down our conversation here, some great advice for folks to think about. But clearly—and I would say this is one of the reasons that we’re both kindred spirits in this—you really care about APIs. It’s clear you think about it a lot. So is that something you expect of others? Do you like folks to care about APIs as much as you do?

Yeah, I don’t expect them to care about it as much when we first start working with an organization, because it’s new, it’s a mind shift. But by the end of the day, yeah, I do. And it might be unfair of me to come into an organization and say, you know, APIs are this important, and you need to dedicate teams to this, and you need to have line items in your budget that handle these particular elements, or you need to do different with chargebacks or whatever, to be able to make sure that you have the right budget to move these things forward. But what I really struggle with, and what I see, is that lost potential, that unmet potential that exists in organizations. There are so many smart people, developers, non-developers alike, all in a variety of different roles in these enterprises, and they’re spending so much time building software. And there is potential in everything that we do to wrap that into an API that people can understand, that has some nice documentation, and make it available for others when the time comes to be able to use it. Not just to think about it as something that’s going to get our data over HTTP, basically just SQL over HTTP and who cares.

It’s hard, because we have to step back as developers, as product managers, product owners, directors, the C-suite, everybody has to step back and realize that to build an API that other people can use requires us to step out of our own selves for a while and think about the needs of other people. And in the midst of the day-to-day, it is hard to do that. But that’s my challenge to teams, to organizations, and to individual teams, and down to the individual developer, product manager, whoever you are, whatever you’re doing in your organization: can you step out of the role that you’re in and think about how you’re delivering an experience to someone else, and how can you make that a little bit better than it was yesterday? That’s the challenge I leave with people. And that’s why I really am passionate about APIs—you can probably tell it from this interview—because it blends business and product and tech all together, it’s really exciting. But it’s an individual that you’re impacting sometimes, not just an organization, it’s an individual’s day-to-day experience. Are you going to give them a good day, or are you going to give them a really rough week where they’re trying to power through something that’s really difficult to use? So I challenge organizations and individuals: how can you make that API just a little bit better? And that goes back to that compass, it goes back to that north point. Are we infecting our culture with a desire to do that, or are we still incentivizing our teams to deliver fast but not to deliver well? And that’s the challenge I leave with a lot of organizations.

Yeah, so powerful. I’m very passionate about APIs, been doing this alongside you for a number of years, and I’ve seen the difference someone who raises that bar to that level can make within an organization—change the tone, change the direction, energize and motivate other folks. I think that goes a long ways. And whether you do that externally coming in as a consultant, or you do that as an internal champion or leader, I think there’s a lot of opportunities for folks to step up to the plate. So someone looking to get into this, maybe make a role change within the enterprise, or maybe become an independent similar to you eventually, what sort of advice do you have for them, James?

I would say first off, learn as much as you can about HTTP, the language of the web. There’s a lot of power in there, and I see a lot of organizations finding some amazing and very creative ways to not use HTTP to its fullest extent. The other is to study software design. Be a student of software design and of products. Go beyond what’s currently trending. There’s always trending stuff, you’ll find more articles about that. Go back in history a little bit, read a little bit about just general software techniques, design patterns and other things, and dig in a little bit and understand a bit more about what came before where you’re at today. Whether you’re a recent grad, you’re still in school, or you’ve been in this industry for decades, several decades, whatever it is, don’t always give in to the new shiny. Weigh it in light of, contextually, what’s the right fit that will make somebody’s life better.

Let’s work together, and as an industry I think we’ve done a really poor job of creating a culture that helps to build appreciation for what’s come before us, instead of chasing that new thing. Most of the stuff that I see today has been around for a while, and when I was starting out in the ’90s, the stuff that was around then was the same stuff that a lot of people had seen before me when I was learning from them. So I think it’s important to step back, weigh those things, thinking about the people that paved the way for us today to do the things that we do, which is just absolutely amazing. Recognize that the context might be different for how we need to build the software, but the principles really remain the same. And there’s just so much to learn out there. So just be a student, look at other APIs, see what other people are doing. And just a gratuitous plug, I have a weekly newsletter I put out where I share a lot of those articles, so you see what other people are doing. It’s called API Developer Weekly, and I just curate articles that are really interesting each week. That’s a great place to start. And then just be a student, learn, grow, get in there, dig in. Think not just about the tech—if you’re on the tech side, learn about some product; if you’re on the product side, learn a little about tech. Learn both sides of it, and you’ll go really far.

So great such a great note. Thank you. And yes, subscribe to his newsletter. It’s kind of been a mainstay of the space for a number of years. You’re going to learn and stay in tune with what’s going on. Thanks, James, I really appreciate you coming on today.

Yeah, thanks, Kin. This has been great. It’s always great to chat with you.

Thank you so much, and we’ll see you soon.

All right, that was fun. Always enjoy talking to James. He’s always a wealth of knowledge and experience, and I really like seeing his view of API operations and how he looks at things. It just really provides a much healthier and more holistic look at how things are going on. So thanks, James, for joining us. I highly recommend that you head over and look at his website. It’s launchany.com, that’s L-A-U-N-C-H-A-N-Y dot com. That’s where you can tap into his consulting services, and he can help you think about your enterprise API lifecycle. I also recommend you check out his newsletter, because he’s got API Developer Weekly, which is at apideveloperweekly.com, and it is one of the top sources for news and information in the API space. I highly recommend you tuning in.

So to give you a little sneak peek into next week: coming up next week we’ve got Lorinda Brandon from BetterCloud. Another friend of mine, I’ve known for years, traveled around the world, had drinks with her in Europe, all around the world as we cruised around talking about APIs. So a wealth of knowledge when it comes to APIs, her experience at SmartBear, Capital One, Twilio, and now she’s at BetterCloud, which I think is really appropriate for this show, because BetterCloud is a SaaS management platform. So they’re going to help you better manage your SaaS service. And with the growth of SaaS and what a big part it is of the software development lifecycle in the overall tech sector, but the role that APIs play when it comes to SaaS, I think is a pretty interesting area to explore. So I look forward to Lorinda joining us next week. I’m going to sit down with her for an hour and see what she’s learned so far. She’s only been on the job for a few months, but I’m curious to learn what BetterCloud’s up to and how she sees the API lifecycle there. Across their teams I’ve met quite a few of them, they’re super interesting folks, been having some great conversations around OpenAPI and OpenAPI-driven lifecycle with their team, and I just look forward to learning more. So tune in next week, you’ll get to hear what happened with Lorinda. And then if you subscribe, you’ll keep being able to tune in, and we’ll keep rolling out new shows. We’ve got some other new segments we’re going to start rolling out as well that dive into specific topics and areas. So stay tuned, we’ll see you next week.