Build catalog versioning with ETags — lab audio overview

Host: Welcome back. You're in AI Developer Platform Engineering — a course about building the internal tools and services that let AI engineering teams ship faster and more safely. This chapter is called Internal Developer Platform Vision, and it's about designing the architecture of that platform — the self-service portal developers log into, the catalog of services they can browse, and the paved, pre-approved paths they follow to get things done. Why does this chapter matter? Because without a platform, every team reinvents the wheel, and nothing scales. Expert: Let me paint a picture of why today's topic matters. Imagine you're on a platform team at a mid-sized company — maybe two hundred engineers, thirty AI services in production. You've built an internal directory — think of it like a phone book for services — where every team can look up what exists, who owns it, what it does. Great. Now two things start happening. First, the directory page gets slow because every developer's dashboard is reloading the entire list every thirty seconds, even when nothing changed. Your network bill balloons. Second, two engineers edit the same service entry at the same time — one updates the owner, the other updates the description — and whoever saves last silently erases the other person's change. Now you've got angry engineers and bad data. Both of these problems have the same underlying solution, and it's a technique that's been quietly powering the web for decades. That's what you're going to implement today. Host: Okay, so before we name what we're building — this is the third and final exercise in this sequence. In the first one, you built the catalog listing with pagination — essentially, showing services a page at a time. In the second, you added search across all those entries, with ranking and autocomplete. What's the third piece? Expert: The third piece is versioning and change detection. Here's the plain-language version. Every entry in your catalog gets a little fingerprint — a short string of characters that uniquely identifies the current version of that entry. If the entry changes in any way, the fingerprint changes. If it hasn't changed, the fingerprint stays the same. This fingerprint has a name in the web world — it's called an entity tag, or E-tag for short. Now here's how you'll use it. When a client — say, a developer's dashboard — asks for a catalog entry, you send back the data plus its fingerprint. Next time that client asks, it includes the fingerprint it already has, and basically says, "only send me the data if this fingerprint is out of date." If nothing's changed, your service replies with a tiny "still fresh, use what you've got" message — no data, no bandwidth. That solves the first problem. For the second problem — two people editing at once — you flip it around. When someone saves a change, they include the fingerprint of the version they started from. Your service checks: does this fingerprint still match what's in the database? If yes, the save goes through. If no, somebody else got there first, and you reject the change with a "try again" message. The client can then re-fetch, show the conflict, and let the human decide. That's the whole idea — one fingerprint, two superpowers. Host: That's a beautiful symmetry. Before folks start coding — what's the one thing that trips people up here? Expert: The trap is how you generate the fingerprint. It feels harmless to just use a timestamp — when was this last updated — but timestamps cause subtle bugs. Two updates inside the same millisecond get the same fingerprint. Clocks drift between servers. And cosmetic edits that don't actually change the data still produce a new fingerprint, causing needless cache misses. The safer approach is to compute the fingerprint from the actual content of the entry — run the data through a hash function, which is just a mathematical blender that turns any input into a short, consistent string. Same input, same fingerprint. Different input, different fingerprint. One other gotcha: the fingerprint must be wrapped in quotation marks when it travels over the network. That's a quirk of the web standard, and if you forget, well-behaved clients will ignore your fingerprint entirely and you'll wonder why nothing's working. Read the spec, wrap the quotes, and test both the "nothing changed" path and the "someone else changed it" path before you call it done. Host: Last stop — what will you walk away with, and where does this leave you? Expert: After this, you'll be able to take any read-write service you build and layer on efficient caching and safe concurrent editing — two production-grade capabilities that separate a toy API from a real one. For your team, this is the foundation of a trustworthy service catalog — one that stays fast under load and never silently loses a teammate's edits. And because this is the final exercise in the objective, you now have the complete picture: a catalog that lists, searches, and versions itself. That's a working internal directory you can bring straight into your team's platform architecture discussions as a reference implementation. Next chapter, you'll start layering the self-service experience on top of this foundation — but the data layer you just built is what makes all of that possible. Go build it. Thanks for listening.