Who are you?

I'm Robert Buchanan, um, coming here from, uh, Procter Gamble where, um, we're doing some interesting things with the API program.

Why do APIs matter?

I mean, APIs have always mattered. The revolution of API is really, uh, in the early two thousands 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 API since computers existed. It's just the exposure now in today's world. When we look at APIs, why they matter is their multi billion dollar avenue for revenue integration, streamlining of conversations between companies, but also internal to companies. So, you know, 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, um, you know, individuals to do the work. Now we can automate that systems. Now we can really do events, um, event streaming and other capabilities to again. Uh, ultimately streamlined to get more products out to answer more business problems and realistically influence our customers.

What is the top mistake you see people make doing APIs?

The biggest mistake I see all the time is. It's, uh, it's kind of twofold. It's realistically, they don't view APIs as more than a technical thing. And really it's a, it's a product. It's an experience. Um, there's a person that worked with me for a long time. They always said in every API governance or style guide meeting is APIs are ugly websites, right? And realistically, if you have a, uh, 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 of, 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, um, you know, challenges in general. So I think one piece is, is. We're not treating 'em as products, we're not putting the time and effort into putting, you know, product on the shelf as with their APIs. They're just technical. And then the other problem is, is the people are taking databases and turning 'em into JSO and calling it an API like, let, let's not do that. That's a massive security problem. And also just horrible design .

Why do people see APIs as just a technical thing?

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 our own fault in the industry of like, I can download this library and, you know, 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 the 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.

Where is the source of truth for APIs?

I would say the true source of truth, like the absolute, is always the runtime. Whatever is active in production is the source of truth. Now, when we talk about communication, documentation, and really how we should engage, The source of truth should be your design 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, like design the contract, you know, design first, do the designing, you know, with the feedback loops and the, the talking with your consumers and stakeholders, and then when you build it, now you can check of. 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 and design focused, much like we have a UX team that is more design focused, and then you had 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 people designing. Because design really takes context knowledge, deep domain knowledge, and really just the user ability or usability of APIs for consumers. It's not just a slap, a few properties in Jason and call it a day.

Should business people be involved with APIs?

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 this stuff is, you know, very, uh, Complimentary 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 on how to use the item. You want to have a good user experience in using the item. You want to have a good, you know, way to purchase the item. If, 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 OpenAPI 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, you know, standardize how we communicate these things. And I did see recently the OpenAPI initiative launched, uh, I forget what it's called, but they're talking about the flows of it. Yeah. ORAZO. ORAZO. 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. Um, and it really, you know, benefits us of that, 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.

Why do you use OpenAPI?

Um, I do feel that the OpenAPI tooling is general public, uh, or the industry is, is limited and we have not done a good job of investing in that tooling. Um, I think what it could offer the potential if, if we changed a bit of the open API specification, be open to, you know, new custom HTTP verbs, or even finding a way to bridge the gap between, you know, synchronous into a similar spec or into that fashion, I think ultimately what it 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 there's people that have done specs to our tools to generate from open API 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. Um, I think the tooling in general, if we. If we had open API, uh, you know, more teams funding it or more company is really attaching to it. We could have a lot more tooling to, you know, really kick people off in the right direction sooner than later. Um, the biggest reason why I like it as a specification is it's one of the more popular ones. Rammel really didn't take off. Um, Smithy is kind of a good, but kind of out there as well from Amazon. But, um, 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.

What are custom HTTP methods?

Yeah. So I think that's a miss in the industry. Um, and the reason why is because we talk about, and I'm going to, you know, hopefully I don't get flack from Roy Fielding, but my understanding of RESTful, um, 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 our So a lot of times I see people, you know, 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 take an event 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. Patches generally not used because they either 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 you're putting that control in the consumer to do. However, if we created a cancel method and you just sent the order slash 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? And we actually would build more secure software because now we've reduced all the logic that goes into processing endpoints, which in turn, if we get to custom methods, more realistically, or, 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 that 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.

Why is it so hard to understand the semantics of APIs?

Oh, absolutely. And I mean, a lot of people go and quote, you know, um, they seem to be 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, you know, we are creating new RFCs for new endpoints, but I think it's, 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, you know, Start to blend when we need things like GRPC, which are very action oriented, very process oriented things, you know, and there's benefits to use GRPC for their low latency and their low or their fast transmission and whatnot. But realistically, we could take some of those learnings and say we can 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 OpenAPI spec isn't enough because a lot of the vendors, like, uh, the CDNs out there, the gateways out there, they restrict you. In fact, um, 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 change it. I love the, the Zig Dev team. Cause they went through with a lot of feedback from the community, went and changed it to where you can now supply custom verbs inside their core system.

What worries you most about the future?

Uh, truthfully, I think the education and the knowledge that we're teaching engineers or software engineers, I, I think, um, and I know Depending on the community, if you use the word engineer, people question, because we're not taking the approaches that other engineer fields do. Right. We're not doing a lot of education in this way. I mean, if you go look out and we have these app schools that are great to get someone started to get into a junior role, 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, uh, rigor to say like, yeah, this is the academic approach. Here's the practical approach. Here's hardened ways to do things. And more and more people are coming out with, you know, allure to tools like, um, a lot of the GraphQL, uh, hype is I can take my database to make an API in like three clicks. because they don't know all the things they don't know. And it's, it's a failure on the IT industry of education. Like 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, the education and the way that we You know, 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.

What keeps you going each day?

Funny enough, it's the reverse of the problem is 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 light 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.