Latest / Tech Leadership with Fexingo: Engineering Managers, CTOs, and Technical Leadership Conversations / What Your Engineering Team Needs from an API Style Guide
Transcript
- Lucas: You know what's one of the most ignored pieces of infrastructure in an engineering org? The API style guide. Luna: Oh, the document everyone says they'll write after the next sprint, and then never does? Lucas: Exactly. And when they do write it, it's usually a two-page Google Doc titled 'API Naming Conventions' that gets referenced twice and then forgotten. But I've been looking at this lately because a friend at a mid-size fintech told me they spent six months cleaning up their API surface after they realized every internal team was designing endpoints like it was a personal art project. Luna: What was the symptom? Slow onboarding for new hires? Lucas: That was part of it. But the real wake-up call was an incident where a payment service returned an error in a completely different format than the billing service. The client library crashed because it expected a string in the 'message' field, but got a nested object. That's a silly way to lose money. Luna: Right, because the client code had to handle both — or worse, didn't handle one and just failed. Lucas: Exactly. So a good style guide isn't just about whether you use camelCase or snake_case. It's about consistency in error formats, pagination, versioning, authentication — the whole lifecycle. I'd argue it's one of the highest-leverage things an engineering manager or CTO can push for, because it touches every team that consumes or produces an API. Luna: Let's talk specifics. What are the biggest things a style guide should cover beyond naming? Lucas: First, URL structure and resource modeling. Are you building RESTful resources with nouns and HTTP methods, or are you doing rpc style actions? If your API mixes both, consumers never know if they should POST to '/orders' to create an order or POST to '/orders/create'. That ambiguity slows down every integration. Luna: Yeah, I've seen teams where half the endpoints are REST and the other half are basically function calls. It's a mess. Lucas: The style guide should pick one and stick with it. Second, error responses. There's a standard called RFC 7807 — Problem Details for HTTP APIs — that defines a consistent structure with 'type', 'title', 'status', 'detail', and 'instance'. If every service in your organization returns errors in that format, client code becomes trivial. Your error handling middleware just parses that shape once. Luna: And it makes debugging cross-service failures way easier. You don't have to guess what 'error_code: 42' means. Lucas: Right. Third, versioning. There's endless debate — URL path vs. header vs. query parameter. I don't care which you pick, but the guide must mandate one approach. The fintech team I mentioned was using all three across different services. That's a nightmare for API gateways and documentation. Luna: So the guide is really about reducing cognitive load. A developer should be able to look at any endpoint in the company and guess how it works. Lucas: Exactly. And that's where the pushback usually comes. Engineers say 'But my endpoint is special, it doesn't fit the pattern.' Nine times out of ten, it does fit. The pattern is flexible enough. But people like feeling creative. The job of the engineering leader is to say, 'I know this feels restrictive, but the consistency will save us ten times the time we lose in flexibility.' Luna: How do you enforce it without becoming a bottleneck? You can't have one person reviewing every API change. Lucas: Automation. Write lint rules that check your API specs — OpenAPI, AsyncAPI, whatever. If a PR adds an endpoint that doesn't follow the URL convention, the CI fails. If the error format doesn't match the schema, the CI fails. The style guide becomes code, not a PDF. Luna: So it's a living document, literally. Do you version the style guide itself? Lucas: I'd recommend it. Start with version 1.0, and treat changes like any other proposal — write an RFC, discuss, ratify. That way, when someone says 'But I want to use a different pagination scheme', you have a process. You don't just break the guide every time someone has a strong opinion. Luna: What about the tension between internal and external APIs? Do you have one guide for both? Lucas: Good question. I'd argue you need a shared core, but the external-facing guide might have stricter requirements — like requiring authentication on every endpoint, or mandating rate-limiting headers. The internal guide can be a bit looser on some things, like allowing gRPC. But the error format, naming conventions, versioning strategy — those should be the same. Otherwise you get context-switching pain. Luna: I remember one org where the internal API used XML and the external used JSON. It was a constant source of bugs. Lucas: That's exactly the kind of thing a style guide prevents. And the nice part is, once you have it, you can build tooling around it. Auto-generate client libraries, documentation, mock servers. All of that gets easier when every service speaks the same language. Luna: It's interesting that you frame this as a leadership topic, not a technical one. Because it's really about getting people to agree on standards. Lucas: And that's the hard part. The technical side is easy — there are good examples out there. Google's API Design Guide, Microsoft's REST API Guidelines, Zalando's. You can start by copying one and adapting. The challenge is social: convincing a team of smart, opinionated engineers that following a style guide makes them faster, not slower. Luna: What's your best argument for that skeptical senior engineer? Lucas: I'd say: 'You're going to spend more of your career reading APIs than writing them. A consistent style guide means you can read any endpoint in the company without context-switching. And when you write a new one, you don't have to make a hundred tiny decisions — you just follow the pattern. That frees up mental energy for the actual hard problem you're trying to solve.' Luna: That's a good pitch. And if they still push back, you can point to data. That fintech team you mentioned — what was the measurable impact? Lucas: They tracked integration time — how long it took a new service to start consuming another team's API. Before the style guide, it averaged two weeks per integration. After, it dropped to under six days. That's a 40 percent reduction. And support tickets related to API misunderstandings went down by a similar amount. Luna: Wow. So the guide paid for itself in a couple of months. Lucas: Absolutely. And the best part is, once you have the guide and the automation, it becomes self-reinforcing. New engineers learn the conventions from day one, because the linter tells them. The guide stops being a document and starts being part of the engineering culture. Luna: You know, speaking of things that become part of the culture, that's exactly why conversations like this one matter. If you found today's discussion useful and want to help us keep having them — ad-free, no sponsors — listeners can support the show at buy me a coffee dot com slash fexingo. It's a small thing that makes a big difference for us. Lucas: Yeah, we don't run ads, and listener support is what keeps it that way. So if you got something out of this, consider throwing a couple bucks in the virtual jar. Luna: Alright, back to the style guide. One more thing I want to touch on: how do you handle deprecation and sunsetting in a style guide? Lucas: Great point. The guide should define a deprecation policy. For example: endpoints must include a 'Sunset' header with a date, and a 'Deprecation' header with a link to the replacement. And the guide should mandate that deprecated endpoints still follow the same conventions — you don't want to start cutting corners just because something is on the way out. Luna: Right, because the whole point is consistency. If someone is still using the old endpoint, it should behave predictably. Lucas: Exactly. And the guide should also cover how to communicate breaking changes. I've seen style guides that require a changelog, a migration guide, and a minimum two-quarter overlap period where both versions are supported. That's the kind of professionalism that builds trust with consumers. Luna: So a style guide is really a contract between the API provider and the consumer, written down. Lucas: That's exactly what it is. And like any good contract, it should be clear, unambiguous, and enforceable. If you're leading an engineering team and you don't have one yet, start small. Pick the three most painful inconsistencies your team faces, write rules for those, and ship them. You don't need a perfect guide on day one — you need a better one than you had yesterday. Luna: And once you have it, you'll wonder how you ever lived without it. Lucas: Exactly. So if you're a CTO or an engineering manager, your action item this week: go look at the last three API changes your team made. If they don't look like they came from the same family, that's your cue.