Subscribe
Share
Share
Embed
Some members of the Stoplight community may have noticed that we are practicing a celebration of "Style Guide September" this month at Stoplight. So, it felt fitting to invite my colleague, Arnaud Lauret (the API Handyman), on to API Intersection to discuss style guide best practices. As the author of the API Stylebook and the novel "Design of Web APIs," this Natixis Senior API Architect was the perfect guest for this topic. In our recent podcast episode, we covered the major style guide tips that will improve your developer experience and level up your API design, including everything from how to deliver a proper design review to maximizing automation and consistency.
Do you have a question you'd like answered, or a topic you want to see in a future episode? Let us know here:
https://stoplight.io/question/
Building a successful API requires more than just coding.
It starts with collaborative design, focuses on creating a great developer experience, and ends with getting your company on board, maintaining consistency, and maximizing your API’s profitability.
In the API Intersection, you’ll learn from experienced API practitioners who transformed their organizations, and get tangible advice to build quality APIs with collaborative API-first design.
Jason Harmon brings over a decade of industry-recognized REST API experience to discuss topics around API design, governance, identity/auth versioning, and more.
They’ll answer listener questions, and discuss best practices on API design (definition, modeling, grammar), Governance (multi-team design, reviewing new API’s), Platform Transformation (culture, internal education, versioning) and more.
They’ll also chat with experienced API practitioners from a wide array of industries to draw out practical takeaways and insights you can use.
Have a question for the podcast? DM us or tag us on Twitter at @stoplightio.
Participant #1:
I'm going to turn the page on my notes or I'm going to get distracted. Okay. Is down. Alright. And I'm going to try Bailey's Marker thing here. Timestamp created. Cool. Yeah. Nice. Alright. Welcome back to API Intersection podcast. We're here again with more of our API geek friends, as also often Adam Evanders doing the co hosting for us today. I think you've already heard about him a bit, but we'll ask him for a quick recap. And then our steamed guest, Arno Laurent, better known as API handyman in some circles. And I guess Adam, give us your quick spiel, which hopefully we've all heard before, just so we know who you are and then to introduce himself.
Participant #2:
I told you good.
Participant #2:
Yeah. I work with API companies to help them reach more developers engage with their API. And I'm excited to hear from our now today because I know he helps make great APIs for those developers. So welcome.
Participant #1:
Yeah. So our node tell us a little bit about your day job, what you're into, kind of what's your story and the API thing here.
Participant #4:
Thank you.
Participant #4:
Yeah. So you said I'm a handyman, but that's my job at night, my daily job. So I'm working for a French backing group called Net is they do Copyright, banking, insurance payments, a difference in actually her setting, banking services. And so have to work with many different teams, many different people to have them understand and create API. So I can I can talk to obviously developers, but also business analysts, product owners, executive. And I try to have all those people do the right API is the right way, but not by actually telling them how to do that. I want to teach them how to do that. So I don't want to bring them fish every day. I want them to learn to fish them stamps. And so I can work with others.
Participant #3:
Yeah.
Participant #1:
Yeah. It's funny. The G word is we call it how do you govern things? And I always think like to people, like, what if you could be King for a day, what kind of King would you be? Right. Help people enable people. Don't be the gatekeeper. I think it's always like a valuable lesson. And I think I've always appreciated that you have that that perspective on things and seems to have made you pretty successful. You know, I think some of this, though, like people get the vibe that you just go around and talk with people and, you know, but there's an operational side to getting this stuff set up and scalable. So how big of a group are you working with here? Like, I don't know a lot about the Texas and how big it is.
Participant #4:
Yeah.
Participant #4:
At
Participant #4:
actually I think there are 16,000 employees. So it's really huge. And this group is actually a part of a bigger group called and so there are many people actually, I'm working with probably at least a dozen of different teams. The last two years. I've done probably around 150 APIs and reviews, and this year we are only in September. And I already have done 160 APIs and reviewed. So there are two or three teams that are actually doing a lot of API stuff. And so but I have to work with many different people, married, many different businesses, business domains, but I actually don't know. And so that's why I cannot do things myself. I'm just here to help people or things. Yeah. So it's pretty challenging to I was alone till recently. I have a new collect now. So go to but the plan is really to enable people. So after working on the reviews, now we are working on more training. And after that we'll do set service training. We are bidding tools. But it's really cool because I've seen so many different things, many different use cases that I have learned a lot. And I'm still learning every day.
Participant #1:
Wow.
Participant #1:
Wow.
Participant #2:
Okay.
Participant #1:
Yeah, it's a person of one for 16,000 employees. It'd be hard not to learn agents.
Participant #4:
Yeah. I think there are 10% of people working in the It. And so I have not two equipment of people in Texas, but it's still a lot of people.
Participant #1:
So. Yeah. So,
Participant #2:
Yeah.
Participant #1:
you know, some of the stuff that you talk about really resonates certainly for us, a stop light. And I think just for me in general, even before I was working in Stoplight is you talk a lot about design first and kind of all that goes into that certainly resonates with us. But I'm particularly interested in this sort of API style book, this collection of style guides that you've done. And for me, like when I look at how do you scale up an API program, what are the things that apply in all those different business domains? Like, that's just a great starting point. There's certainly other factors, but I'm curious, how long have you been running that style book site now?
Participant #4:
I've studied it. I think it was probably three, three years or four years ago. To be honest, I have not updated it since I started to work on my book. So maybe it has not been updated. Two years ago I started to work on it. Now I have probably five to ten guidelines. Too hard. I need to revoke the warping because it's really or full to maintain. But yeah, it started a long time ago. And actually the idea was I was trying to build guidelines myself, and I found a few ones. I started to read them. And it was complicated because I wanted to know, how do people manage reading something, deleting something and constructing path, because at that time I was really focusing on just the form of APIs but I discovered reading those guidelines that some of it contains information about more organizational concerns, the G word governance, and how sometimes also some little guidance about how to analyze what the domain you want to turn into APIs. And so it really enlightened me because I realized that API design is not only about just choosing will I do get customers or get customer without an S. And it's funny because when I start to work with a new team with new people who don't know me for a review, they came to me saying, okay, it seems that we are supposed to talk to you to be able to deploy our API on the API gateway. Say no, I'm not here to do that. And it seems that you should validate our API design. So you see, we have done get Vs and say no, no, this is not what we are talking about here. I'm here to help you create the best possible API. And it's not only about get sent back, so that really helped me. And I hope that it actually helps over. But I really need to rework it because new guidelines that have been published by many different organizations, especially government, and there are many very interesting thing to share. But I need to make the world stuff more automated because I I do that with totally YAML files, reading the documents myself, copy pasting it. It takes hours to put a guideline on the website.
Participant #1:
That's what.
Participant #1:
Yup.
Participant #2:
Well, it sounds like when you started that process, you needed to sort of go deep into that to be able to figure out what you were going to put into your own. What what were some of the things you pulled out from all the guidelines you found available that you then included in the guidelines that you share with the team you work with?
Participant #1:
Okay.
Participant #4:
Yeah, yeah.
Participant #1:
Okay.
Participant #4:
Things like very technical thing. Search about how to explain why you should us get post to whatever the very basic things. We also think about more organization, how who should divert the reviews and so on. But for me, it was really only the beginning. Afterwards, I will learn a lot by actually practicing doing APIs and reviews. And I also take advantage of what are learned by listening to people talking about API documentation, because there is a lot between typical API documentation and typical API guidelines, especially when it comes to the form of things in your guidelines and in your API documentation, you will have some kind of the reference documentation, the ingredients for the API. It would be okay. We have a get a BS and a post. That okay. That ingredients for the guidelines. It's okay. The path are structures. That way we use these Http codes in a situation and so on. Ingredients and afterwards was if you just provide that to people, they can't do anything with that, especially people who are actually beginning before you are not familiar with the Http protocol, people who are not developers. I work with API designers who are not developers. There are business Artanis sometimes. And so I decided to add in age lines the kind of use case documentation. Okay, these are all your end points, and you can use this one and this one and this one that way. In that order to do that, that is a use case documentation. And I added that in my guidelines. And I always say to people, don't look into the the rules, don't care about that. Just look at the recipes. You want to create something. You want to list something you want, start shopping. Whatever you want to do varies the recipe explaining you everything.
Participant #3:
Okay.
Participant #2:
Yeah.
Participant #1:
Yeah, I think you're talking about kind of guides and documentation, but walk me back through, like, how do you see that parallel to the way that style guides are defined?
Participant #4:
Actually, no. If my memory is correct, my memories are correct. In the guidelines that I have seen in VPI Stylebook, most of them are focusing on rules. For example, I remember that there is the Zalando style guys. There are hundreds of rules. At least it was that way the last time I've seen it. And every role is quite clear, but I wonder actually how people use them because there are many rules. And in the specific use case, what do you have to do? You have to do over rules and be sure of the ones you actually have to apply. That's a little bit complicated. So then I have to check again for new Airlines. But I have actually not seen guidelines focusing on typical API use case because even it fits. Actually bad to say that rest API or API actually crud API's. But actually if you look at all APIs or of they all use the same kind of operations you read. In elements you search for elements you are creating elements you are tenements. Whatever you do, simple things or complex things, there will be put into an API using those typical operation. So if you provide the recipes to handle those difficult operation aggregating all the rules that apply, people will have a much easier time to when designing.
Participant #1:
Yup.
Participant #1:
Yeah, I see what you're saying.
Participant #1:
Okay.
Participant #1:
Yeah. I think this matches up with how guidance I might give folks on this stuff sometimes is like for the predictable rules, the things like, you know, is it spine case or is it Camel case how many past components are allowed? How do you do paging across most things? Right. Stuff that's predictable and automatable. Do it and have that stuff strongly defined so that you can spend most of your time talking about what does this do and more importantly, what's the flow. So if you have I'll take, like, a PayPal example that a lot of people are familiar with that I worked on a lot is you can't make a payment with one call. Right. You have to get an authorization, and then you go through this disconnected third party weird of flow, and then you actually complete the transaction. So there is inherent flow across those APIs, and there's no style guide for how to do that. Right. That's kind of the substance of it and where you want to spend your energy on. But I wanted to key in a little bit. You were saying, like, some places have these really detailed rules. Right. Like, the rule sets for sort of governing style are very precise, and it can be tedious to process and apply that and more importantly, to, like, teach it and have folks, in your words, be able to fish for themselves. So, like, how have you seen that dealt with to make it scale better and kind of provide consistency?
Participant #4:
Yeah, yeah,
Participant #4:
yeah.
Participant #4:
Nope. Yeah, yeah, yeah.
Participant #4:
Regarding system or to site, there is okay, there are two sites. There is what you can automate, because if people are not using communicate, not using the correct pastures and whatever I can automate all that, you can also force a intimate questions. Actually, I'm using spectral sometimes just I'm creating word just to warn me. Oh, there is something here that should be discussed with the AP item. Yes, I'm using actually, error is an actual error. You have to fix it. Warning is maybe an error. And there is info and hint.
Participant #1:
Well, let's call it how do you put a style guide into operations, in your opinion?
Participant #1:
Meaning sort of the info versus the errors. Is that what you're getting at? Right.
Participant #1:
Yeah. And I guess for listeners here before you get too far spectral that our nodes are referring to. And by the way, I didn't bait him on this at one of Stop light open source projects to do sort of linting of these rules and basically automate some of the the style guide governance stuff
Participant #4:
Yeah, yeah,
Participant #4:
yeah. That's yeah.
Participant #4:
And afterwards it's actually teaching people to understand the concerns regarding consistency because at the beginning, most people actually don't care about it or are not aware of it. And yeah. And so it really it's really along. It's a long run work. You have to do reviews, a star reviews, and that slowly but surely people get it and people are getting better it once you have show them the actual problem. The typical example is okay. I'm I'm searching for bank accounts or customers or whatever. I can use filters on this research on names or and most of the time the first when I meet people for the first time, they do the this mistake. They are heading third filters that do not match the data returned. For example, you are looking for customers. They say, oh, we want to filter on gender, whatever, but there is no gender in the data, or gender is name with another name and say, hey, this is a consistent people should be able to think, okay, I know what a customer are all as all these properties, so maybe I can use all of them. Or some of them are query parameters without reading the documentation and by just showing them by example, using their own design. After a few reviews, people actually get it. And I think that afterwards, but you cannot. You cannot remember everything. Actually, I think I have a very good memory because I'm working with very different teams and for a long time, so sometimes I know their APIs better mandator owner, so I'm able to save them. Okay. I remember that you already designed with data structure in another API, so you better check that in the new API. You are actually maybe not using the exact same structure, but keep the spirit of it. And doing that requires to really know all of your APIs. And I'm planning to work on a tool that will is bad job, especially during design, because sometimes as a designer, you wonder, okay, I'm working on that domain. I want to add a new property in that schema or in schema, but does it already exist somewhere in my API surface? And there is not there is no tool actually that provide that. Sometimes I basically choose very done a simple search across all the open API files I have, and I do the trick, but I want to provide something more user friendly, and so that's it with automation practice and having VI of a designer and tools that allow you to search through all of your API's descriptions, dams, and so on. I think that this will help you to ensure a certain level of consistency that people should be aware of that they will do mistakes, whatever they will do mistakes. So with reviews, you will maybe a advent, but sometimes you will have to live with them.
Participant #1:
until you block or deploy.
Participant #1:
Okay.
Participant #1:
Yup,
Participant #1:
Yup.
Participant #1:
Yeah.
Participant #2:
Yeah.
Participant #1:
Yeah. Well, there's always come compromise you.
Participant #2:
And if we could go back to the to the automated piece where you said that they kind of learn what those consistency rules are. Who are the people who are using those automated searches? That at the engineering level? Is that still at the business user level? Who is attempting to design the API?
Participant #4:
Yep. Yep.
Participant #4:
So are you talking about the automatic controls of research? Okay, the controls. So actually I started to promote. And again, I'm not paid by Stop Light, but I'm just using virtual because we are actually good. So I'm promoting the use of the Stop Light Studio because before that, people who are business analysts were trying to actually write open API specification, and it was really the burden from them. And there is no need for that because there is a graphical user interface that avoid them doing that, actually. And in Studio, they can use our spectral rules. So you can connect studio to specter rules, and so we can check the design is actually conforming to our gallon. But I have to be honest, sometimes, maybe more often than not, people actually don't use the rules, don't use Spectral. So now in the training session that I'm building, I'm showing people how to actually do that, but sometimes they are not using it. That's why we need still need the review process so they can understand that they can gain time or whatever. But it's really a long run task because you have to change habits to make people use tools. Maybe they are not used to. So it's not. It's not that easy. It's not magic.
Participant #2:
The first one? Yeah. The controls.
Participant #2:
Okay.
Participant #2:
Yeah.
Participant #2:
Yeah.
Participant #2:
Yeah. So
Participant #2:
yeah. But it sounds like the spectral output, regardless of whether they used it. So if they used it up front, probably the errors are going to go away, but there's still regardless of whether there's errors there or not, there's stuff within that that is going to promote a conversation with you. Is that how it does? Okay.
Participant #1:
Yeah.
Participant #4:
Yeah, yeah, yeah, yeah, exactly. Because I remember a few weeks ago review with a team who actually is using the tools. So. Okay, we tried the designer. I try to get rid of all errors. Most of them. Most of the arrows are fixed, but there are still a few things to fix. But most of the time we spend together we were discussing on things that Spectral was enable to detect because no tool enough could detect them because it was more business concerns. Okay. Yes, exactly. What do you want to do with your APIs and how you want to do it? And what are the rules of your domain? Why do you name this like that? Is it? Yeah, exactly. And I say that every day. Stupid question. Every day. If you want to be a good API design reviewer, you must not be afraid to ask stupid questions and it's really for the better.
Participant #1:
Domain subject matter stuff. Yeah.
Participant #2:
Yeah.
Participant #1:
What does that word mean? Yeah,
Participant #2:
Yeah.
Participant #1:
absolutely.
Participant #1:
So I wanted to kind of capture you picked off a couple of things in here that I feel like we're establishing as table stakes in your world to make this kind of style conformance and good design work. One is you were touching on kind of discoverability is what I would call it. Like, do you have a place that you can search across all the APIs, look across all of them in one place? You got to have that. Otherwise, these pattern istic things are undetectable. So I think that's one you mentioned kind of that open API certainly being a prevalent format. There's certainly others out there. I mean, you've got, like, gRPC and protobuf stuff and open the sync API for events, and there's certainly a variety of these, but that people learning how the spec works shouldn't be a thing and find a tool to do that for you. And then I think, in essence, what we were kind of circling around is that using automation for your style guide to produce some kind of conformance understanding, make space to have discussion about what the thing does and what it is, which, by the way, I think you're a 14 guest or something has been in every conversation, and it's so obvious and it's so simple and it seems pedantic to say it. But I think for folks like us who sat with developers who built up some API and go, what does this thing do? And I can't answer it, it's stunning how often that's true, I guess. Any other thoughts we got? Discoverability kind of ease of editing some form of automated conformance to your basic conventions, and then having conversations about the functional view of it all. Is there anything else when you think about our G word friend that you know that we're missing?
Participant #3:
Okay.
Participant #4:
Yeah,
Participant #4:
yeah,
Participant #4:
yes, exactly.
Participant #4:
Ah.
Participant #4:
Oh, yes. It's about how to and vision governance from the human perspective, globally and more specifically during API even review. So if we just look at API design review, actually, there are two ways of doing an API in review being a Nestle, just doing the police yelling at people that there is a seed. We are not respective. They are not respecting. The rules are actually breaking below that. We go in jail or whatever making them and scary. It depends on who I'm talking for. Yeah, that's actually what I try not to do. And Sofia Way is actually show in Bessy two of us and not take the API design review as a way to do control, to control things, to make sure that people do actively their job. That to be a helpful hand. An API design. When I meet people for the first time, I explained what is an API design review for me and in my company, and I said then that I am here to help you. I am not here to tell you that what you do is wrong. I am not here to tell you how to do your API. I will explain you design principles based on what you show me. I will give you values proposition about how your design can be modified, fixed, and you will tell me what is your context. And together we will discuss. And in the end you will decide based on what you have realized about your context and what you have discovered about design in general, but in the you make the decision. I'm not here to do that in your place, and that actually works very well. The other one actually does not work. And that stance, being the evil Empire of API design, can actually kill your company. Because if you do that, the follow will not learn their on their second review, they will say, okay, I don't know how to do this. Do it for me. I'm just a small product owner. I am just a small business analyst. I had to deliver my project in two weeks, so please do that so we can go quickly, and I leave the keyboard to you. And that so people don't learn anything before are frightened, and people don't like you. For some people, it's not a problem. But it's really not a good environment for people and really being trying to teach people to have them, to let them do maybe sometimes mistakes. Surprisingly, they come back and we tell everyone, okay. It's really good to work with this team, and they help us. And and so we have I'm really happy to have really good feedback because of that. And not because I succeed to with a very strong hand to break arms and make people do API fanatics this way.
Participant #1:
Yeah.
Participant #1:
Yeah.
Participant #2:
So that's the one you do, but.
Participant #1:
Okay.
Participant #1:
Yeah.
Participant #2:
Yeah.
Participant #1:
Well said. I think along the lines of thinking that engineering teams tend to lack design thinking. Empathy is always rule one, right. And again, we've heard it before on here from other folks that do it. And I think within that kind of this enablement model of like, we're here to make you look cool, I make you look consistent with everyone else that works. I agree. So,
Participant #4:
Yeah.
Participant #4:
Yeah, yeah.
Participant #4:
And what I really love is that a few months ago, a developer who has been working with me totally. Okay. I was not aware about API design and so on and so on. And now I'm using VPI Deen principles. My God, I'm trying to think about, okay, why I'm creating this function, how how to name me, how to name parameters, how to. And because the API design you are preaching actually are principles that you can apply everywhere. We are talking about user experience making things that are actually fulfilling, but our solutions to existing programs either you do API. If you are doing a mobile app, you are creating a batch server application, whatever. It's all the same stuff.
Participant #1:
yeah. Design it.
Participant #1:
Yeah. I think, like designing a system in general that there is a design component to that that people often look at wrong. And it's like I'll take an easy to understand a comprehensible system over a high performing one any day. I can make a system perform if I don't know what it does and we have to rewrite it, then that was a huge waste of time. So great stuff today, really. I think you very succinctly punched through, I think, some of the fundamentals of governance. And it's funny. It we've heard from so many people, like, start with the style guide and it will lead you to the rest. And that's exactly what you just walked us through. So fantastic in line with what we've heard before. So I think that it serves as a perfect place for us to wrap up. So just want to totally thank you for coming on. Really appreciate our Node and Adam for joining us yet again. All right.
Participant #4:
Yeah,
Participant #4:
yeah, yeah, it.
Participant #3:
Yes.
Participant #2:
Yeah. Thanks for having us
Participant #4:
Yeah. Thank you very much for having me. And it was really presale. And I look forward to hear the other people in the next episode.
Participant #1:
Yeah. And if you haven't read it yet, make sure and go look for the design of web APIs. It's available in all kinds of cool languages with really cool covers that I geek out about. That's our notes book. There you go. If you're on video, Adam just held it up as well as API Stylebook com, which apparently hopefully by the time this actually goes out, we'll be refreshed. Our net has been productive in the interim.
Participant #2:
Yeah.
Participant #4:
No.
Participant #4:
Bye.
Participant #4:
Yeah. If I don't sleep, maybe. Thank you.
Participant #1:
Nice. Alright. Thanks, everyone.
Participant #1:
Okay. And recording has stopped. So.