Implement catalog listing with pagination — lab audio overview

Host: Welcome back. You're in AI Developer Platform Engineering — a course about building the internal tools and systems that let engineering teams ship AI applications quickly and safely. This chapter is called Internal Developer Platform Vision. That's a mouthful, so let's unpack it. An internal developer platform is basically a private toolkit a company builds for its own engineers — a self-service menu of approved building blocks. And today's skill — pagination — is the piece that makes that menu actually usable when it grows. Why does this matter in a real production setting? Expert: Picture a mid-sized company — maybe eight hundred engineers, thirty platform team members. Someone on the platform team builds an internal website where any engineer can browse approved services — the company-blessed database, the company-blessed message queue, the company-blessed model-serving setup. At launch there are twelve services, so the page loads instantly. Two years later there are four thousand entries — every model, every dataset, every shared component. Now the browse page takes eighteen seconds to load, the mobile view crashes, and two engineers complain that items seem to shuffle around while they're scrolling. That's the moment the platform team realizes they never designed for scale. The fix isn't a bigger server. The fix is pagination — handing out the catalog in small, predictable chunks. This is the foundational skill for anything that lists things in a production system. If you can't paginate reliably, your internal platform will break the day it succeeds. And that's exactly the exercise you're about to do. Host: Good — so this is the very first exercise in the sequence, meaning you're starting fresh. The chapter overview walked through the big picture of what an internal developer platform is. Now we get hands-on. So what, concretely, are we going to build? Expert: You're going to build the part of the internal platform that lists services — think of it as the back-end logic behind that browse page. When someone asks for the catalog, instead of returning all four thousand entries at once, your code returns a small window — say, fifty items — plus a little bookmark that tells the next request where to pick up. That bookmark is the key idea, and it has a name: a cursor. Here's the aha moment. Most people, when they first think about pagination, imagine page numbers — page one, page two, page three. That works for a printed book, but it's a terrible fit for a live catalog, because services are constantly being added and removed. If someone deletes an entry while you're on page three, suddenly page four's contents shift backward and you either see an item twice or miss one entirely. A cursor avoids this. Instead of saying "give me page three," the client says "give me the fifty items that come after this specific marker." The marker points to a real entry — usually by its unique identifier or a timestamp. So even if the catalog is churning underneath you, your traversal stays stable. That's what "stable traversal" means in the exercise description. You're also making the page size configurable — meaning the caller can ask for ten items or a hundred, within sensible limits you set. Host: That makes sense. Now — before someone starts coding — what's the part that usually trips people up on their first pagination implementation? Expert: The trap is the cursor itself. People's first instinct is to use the position in the list — "item number one hundred and fifty" — as the cursor. Don't do that. Positions shift when items get inserted or deleted. Instead, your cursor needs to be tied to a property of the entry itself — something that doesn't move. The most common choice is the entry's unique identifier combined with the field you're sorting by. So if you're sorting the catalog alphabetically by service name, the cursor encodes the last service name returned plus its unique ID as a tie-breaker. The tie-breaker matters because two services could have the same name, and without it, your pagination will skip or repeat entries right at the boundary. Second tip: encode the cursor as an opaque string — something the client passes back without trying to read or modify it. That way you can change the internals later without breaking every caller. Test it by paginating through the whole catalog while simultaneously inserting and deleting entries, and confirm you see every stable entry exactly once. Host: Great — that's the kind of detail that saves hours of debugging. Let's close out. What will the listener actually be able to do after finishing this, and where does the sequence go next? Expert: After this exercise, you'll be able to take any large, changing list of items and serve it to clients in stable, bite-sized chunks — no matter how big it grows or how much it churns. That's a genuinely foundational building block. Your team can use this same pattern for listing models, listing deployments, listing training runs, listing anything. It's the kind of primitive that shows up in every production data system, and once you've built one correctly, you recognize the shape everywhere. In the next exercise, you'll extend this catalog to support full-text search — meaning engineers can type a few letters and get relevant matches, with autocomplete suggestions and ranking by relevance. You'll combine that search with the pagination you just built, so results come back in stable chunks even when they're filtered. And the third exercise after that tackles versioning — making sure clients can tell when the catalog has changed without re-downloading everything. Together, those three skills give you a production-grade service catalog — the beating heart of a real internal developer platform. Host: Perfect. So: cursors over page numbers, tie-breakers on your sort, opaque tokens for the client. Go build it, and we'll see you in the next one. Thanks for listening.