API Evangelist Conversation with Robert Buchanan, API Evangelist Driving API Integrations and API First practices at Procter & Gamble

Hello there, Kin Lane here, API Evangelist, here for another one of my API Evangelist conversations where I just talk to folks who are doing interesting things in the API realm. So let’s make this happen, let’s see who we’re talking to today. Hey, now, who are you?

Hey, I’m Robert Buchanan, coming here from Procter & Gamble, where we’re doing some interesting things with the API program.

Nice to have you, Robert, always love chatting with you. Robert was, just for everyone, for Breaking Changes, I would say he was the back channel all through Breaking Changes, but I never properly got him on the show. Like, him and I were talking pretty much weekly and talking through things, but he never made it on the show proper, so I want to make sure Robert gets some good airtime here. But let’s start with the basics, Robert. Why do APIs matter? Why are we here talking today?

I mean, APIs have always mattered. The revolution of APIs really, in the early 2000s when Roy Fielding came out with the RESTful architecture, and really the coining of web services, really kicked it off. But we’ve been using APIs since computers existed, it’s just the exposure now in today’s world. When we look at APIs, why they matter, they’re a multi-billion-dollar avenue for revenue, integration, streamlining of conversations between companies, but also internal to companies. So with that massive popularity and the value-add that they can bring, we can now start answering a lot of problems that previously took a lot of individuals to do the work. Now we can automate that with systems, now we can really do event streaming and other capabilities to ultimately streamline to get more products out, to answer more business problems, and realistically influence our customers.

Yeah, agreed, 100 percent. So I think people get the API thing, everything you said, why it matters, but I see teams making a lot of mistakes and repeating, it feels like we’ve been saying the same things for a long time. What’s the top mistake you see teams making at all the places you work throughout your career?

Probably the biggest mistake I see all the time, it’s kind of twofold. Realistically, they don’t view APIs as more than a technical thing, and really it’s a product, it’s an experience. There’s a person that worked with me for a long time, they always said in every API governance or style guide meeting, APIs are ugly websites, right. And realistically, if you have an API which is not usable by a customer or usable by a developer, it’s not a great API. And a lot of people think, well, this company has to use our API, well, the biggest mistake is not making it a good API or a good consumer experience for the API consumer, because then you have more support tickets, you have more flaws, you have more challenges in general. So I think one piece is, we’re not treating them as products, we’re not putting the time and effort into putting, you know, product on the shelf as with our APIs, they’re just technical. And then the other problem is that people are taking databases and turning them into JSON and calling it an API. Like, let’s not do that, that’s a massive security problem and also just horrible design.

So why are APIs just a configuration thing, why do people see them as just technical? Is it because IT led the thing, there’s not enough business involvement? Why are they just technical?

So I think a lot of it is business wants to do it fast, they don’t do proper funding on development, they hear buzzwords from the industry. So partly it’s already a pitfall in the industry of, like, I can download this library and build an API in minutes. Well, no, you can get started in minutes, you can’t finish in minutes, right. It’s a lot of the big hype of AI right now, it’s like, oh, I can generate a website from an AI prompt. Sure, but there’s a lot of problems with those prompts, there’s a lot of problems with the end result. Could you get the base started? Absolutely. Now start tweaking and enhancing it, that’s where you need the knowledge and expertise. We’re forgetting to have that knowledge and expertise and this, I don’t know, handcrafted, taking pride in your work kind of approach to APIs.

I see a lot of argument, a lot of discussion on different approaches, design-first versus code-first, we’ve got all these, but I’m more interested in where do you see the source of truth when it comes to this work on APIs? What is actually the most meaningful representation of an API across the enterprise landscape, would you say?

I would say the true source of truth, like the absolute, is always the runtime, whatever is active in production is a source of truth. Now when we talk about communication, documentation, really how we should engage, the source of truth should be your designed contract, and it should be held as a contract in the sense of, you can’t just change it and break all your consumers. And I think that’s where a lot of people who go code-first and then have something spit out their documentation lose the ability to vet their assumptions and what they’ve done. Design the contract, you know, design-first, do the designing, with the feedback loops and the talking with your consumers, the stakeholders, and then when you build it, now you can check, this is what I thought it was going to be, this is what it actually is, is it still matching? And really, I think the combination of those two is really the source, because then you can check your own work, you can also have people who are more architectural, design-focused, much like we have a UX team that is more design-focused, and then you have the UI team who’s more implementation, you can do the same thing, to where implementation needs to follow the design, but your implementers are not necessarily the people designing, because design really takes context knowledge, deep domain knowledge, and really just the usability of APIs for consumers. It’s not just slap a few properties in JSON and call it a day.

Is this something that real, actual business people should get involved in, this whole process, and should they concern themselves with the API life cycle?

I believe that if you are treating APIs as a product, any product manager who has an offering that includes APIs should have at least, you know, 101 and maybe even 201 knowledge of APIs. They should understand the patterns, they should understand what makes a good API, and a lot of the stuff is very complementary to what they already know of software products or even physical products, right. If we look at any item on the shelf, you want to have good documentation of how to use the item, you want to have a good user experience in using the item, you want to have a good way to purchase the item. If you don’t have those things, you’re not going to sell many items. And I think that’s where product really needs to step in and not just say, oh, it’s a technical thing, it’s just an implementation, but more of, again, taking that pride in the work of saying, this is something I’m selling, this is something, even if it’s to the team next to me, they’re my customers, I’m selling it to them, I need to make it good so they love it.

Is that why you called OpenAPI a contract? There must be a contract.

Yeah, OpenAPI is a contract. Now, the OpenAPI spec, as we’ve talked many times, is limited, and I wish it was a bit more open than it is, but it is a contract that helps us standardize how we communicate these things. And I did see recently the OpenAPI Initiative launched, I forget what it’s called, but they’re talking about the flows of it.

Yeah, the Arazzo.

Yes, yeah, so that, I haven’t taken a deep-dive look into it, but it does help part of that contract in the documentation of, like, here’s a way that people use this contract to get the job done. And it really benefits us of that contract to say, this is how you interact with it, this is what’s required for us to process the data, but ultimately you need to decide how you’re going to use it as a consumer, we’re just here to help you use it, right.

Yeah, and I think that’s a key part of getting those business stakeholders involved, but I think most people just see OpenAPI as just for docs. Like, what’s the top two reasons you recommend using OpenAPI?

I do feel that the OpenAPI tooling, in the general public or the industry, is limited, and we have not done a good job of investing in that tooling. I think what it could offer, the potential, if we changed a bit of the OpenAPI specification to be open to new custom HTTP verbs, or even finding a way to bridge the gap between synchronous and asynchronous APIs into a similar spec or into that fashion, I think ultimately what we could drive is a lot of ways that we can build implementation tools to even generate some of the code in a more profound or robust way. I know there’s currently generators, and people have done specs or tools to generate from OpenAPI spec, but it’s not something a company can quickly pick up, conform to their core engineering principles or their core engineering libraries and whatnot, they have to restart the whole process over and over again. I think the tooling in general, if we had OpenAPI, you know, more teams funding into it or more companies really attaching to it, we could have a lot more tooling to really kick people off in the right direction sooner than later. The biggest reason why I like it as a specification is it’s one of the more popular ones. RAML really didn’t take off, Smithy is kind of good but kind of out there as well from Amazon, but we can use it as a talking point in conversations, right. And like any contract, you need people to review it, you need people to read it, you need people to understand it, and it’s at least a way to get it in front of folks, either in a configuration file as a source of truth in a GitHub, or by rendering it with a tool like Swagger UI or Redoc or RapiDoc. So it’s a conversational piece to get the feedback loop started.

Yeah, it’s critical for that from a technical, an engineering perspective, but also that product, and I think that bridge-building between them is key. But I want to dive in on a specific thing, because we’ve talked about this many times before, and I was pushing on Postman to get what you wanted when I worked there, but custom HTTP methods? Wait, there’s just get, post, and put, and occasionally patch and delete, like, what are you talking about?

Yeah, I think that’s a miss in the industry, and the reason why is because we talk about, and I’m going to, hopefully I don’t give flack from Roy Fielding, but my understanding of RESTful and whatnot is, we should be able to define HTTP methods so that our actions are communicated in the methods, the verbs of what we’re trying to do are communicated in the HTTP methods, but not necessarily in our payload structures or in the URL. So a lot of times I see people get caught up in the conundrum of, if they’re trying to build an API to where they process orders, they’re like, well, how do I cancel an order? Well, it could be a post and you’ve taken a verb to cancel an order, it could be a put where you update the order, but now you’re putting the control of what status it is into the consumer’s hand, and then it could be a patch, but patch is generally not used because either they don’t do a JSON patch or they don’t do a proper patch operation, they do like this merge or upsert system, and again, it goes back to putting that control in the consumer to do however. If we created a cancel method and you just sent the order ID with the cancel method, now your logic is very crisp and clear of, hey, I need to cancel this order, I don’t have to guess of, well, is it modifying the fulfillment address, is it modifying this. We actually would build more secure software, because now we’ve reduced all the logic that goes into processing inputs, which in turn, if we get to custom methods, or more methods in general, we would then get to that holy grail of hypermedia a lot easier, because then when we pass around the links in payloads, they become easier to decipher programmatically versus, like, well, is this a post, it’s saying action of, you know, next, is that a post, is it get, is it a what, what is it, right. We can clearly say what it is because the methods are available.

Yeah, I like it. I do a lot of harvesting of APIs for my API search engine, and so I harvest the OpenAPIs, the Swaggers, as well as parse their docs, and I get paths, I get the HTTP methods, parameters, as much about that operation as I can, and semantically trying to understand what the hell is going on and what the intent was is just maddening sometimes.

Oh, absolutely, and I mean, a lot of people go and quote the HTTP spec, and like, well, you know, gets don’t deserve bodies. Okay, but query is a new RFC that’s out there for a new method, it is effectively a get with a body, because it’s doing all the semantics of what we use post for for searching, but it’s putting it into a way that you can do it over a query method, which is a subset of what get did. So we are creating new RFCs for new endpoints, but I think those are great for, like, the global standards, but I think companies in general should be able to draft their own for their own company canonical use, because it would expand a lot of what we’re doing inside of APIs, and it also starts to blend when we need things like gRPC, which are very action-oriented, very process-oriented things. And there’s benefits to use gRPC for their low latency and their fast transmission and whatnot, but realistically we could take some of those learnings and say we could apply those to even RESTful endpoints, because we have the other verbs to describe what we’re doing. I think it’s a miss in the industry, and sadly changing the OpenAPI spec isn’t enough, because a lot of the vendors, like the CDNs out there, the gateways out there, they restrict you. In fact, I submitted an issue to the Zig programming language, because their first implementation of an HTTP server at the core language only supported certain verbs. I said, well, the spec says this, and they actually went through and changed it. I love the Zig dev team, because they went through, with a lot of feedback from the community, and changed it to where you can now supply custom verbs inside their core system.

Well, we may have to have you back and talk about this, because you mentioned the multi-protocol switching, and you know me, I’ve done a lot of work with async and gRPC, different things, and that kind of shifting gears, but also AI, I’m really diving into JSON-LD and ALPS and other semantics as a layer around individual OpenAPI, like one-operation-type OpenAPIs. How do you have a conversation with a series of API calls defined by OpenAPI, what are those nouns and verbs? And so I think we’re going to have to dive into this, but I have two questions, one a little darker, and then we’ll get lighter. Before I let you go, what worries you the most about the future or future generations and what we’re building and what we’re doing right now?

Truthfully, I think the education and the knowledge that we’re teaching engineers or software engineers. I think, and I know depending on the community, if you’re an engineer, people will question, because we’re not taking the approaches that other engineering fields do, right. We’re not doing a lot of education in this way. I mean, if you go look out, we have these app schools that are great to get someone started, to get to a junior role, but the companies aren’t taking that education and then doing more with it, right. We’re kind of putting people into the deep end with just enough knowledge to be dangerous, but we’re not hardening them with the foundations or, you know, computer science rigor to say, like, yeah, this is the academic approach, this is the practical approach, these are hardened ways to do things. And more and more people are coming out with tools like, you know, a lot of the GraphQL hype is, I can take my database and make an API in like three clicks, because they don’t know all the things they don’t know. And it’s a failure on the IT industry of education. It’s almost as if, and I hate certifications, because it’s usually book knowledge versus practical knowledge, but it’s almost like companies should have a way to do continuous education with their engineers as a requirement for them to be safe and to be knowledgeable. But I do think the education and the way that we hype everything up as quick and easy is our downfall. It’s going to make it to where we lose a lot of that lower-level language, lower-level thought process, and really solving real problems versus solving semantic sugar problems.

Yeah, well, I know firsthand VCs won’t let you invest too much in education when it comes to your startup, so they cut it off there, and there’s a lot of other problems. Now, one more positive side, what keeps you going, what keeps you coming back every day to the API realm and doing what you do?

And funny enough, it’s the reverse of the problem. I like teaching, I like mentoring, I like telling people experiences and collaborating with them. It’s honestly why even after doing this is now my second API program at two different employers, I’m still going to be involved in the space and continue doing it. I’m taking more of a security approach this time, because it’s a big threat vector out there, but really it’s, if I teach people to build better APIs, more secure APIs, that threat vector becomes more manageable, right. So much as I feel the industry is failing on the education side, where we have too much high-level education, I’m trying to instill a lot of lower-level education within the people I talk to, and really share with them experiences to build better systems.

So critical, so important. Always a pleasure, thanks for coming by, Robert.

Absolutely, anytime, Kin.

All right, definitely going to have him come back and talk more about the semantics at the HTTP method layer. The education piece is huge, I definitely support him on that. But anyways, till next time, everyone, thanks for coming by.