REST API Design for AI: Routes, Resources & Reality

Key Takeaways

Welcome to module two. In module one, you got fast API running, understood the async model, and saw how automatic doc works. Now we go deeper. Before we write real endpoints, we need to understand how to design them well. That starts with REST. In this video, we will cover what REST is, how routes and HTTP verb works, and when REST is the right mental model for AI APIs. Now, Karan got his first app running. He saw the docs, hit his hello world endpoint, and felt good. But now he's starting at a blank file thinking about his actual project. How should I name my routes? When do I use post versus get? What does a well-designed API even look like? These are the questions we are going to answer right now, and it starts with understanding REST. REST stands for Representational State Transfer. Don't worry about the name. What matter is the idea behind it. REST is a set of design principles that tells you how to structure your API. The core idea is simple. Build your API around resources. A resource is any piece of data your API manages. In an AI backend, that could be a user, a document you have ingested, a chat session, or a query result. REST says, give each resource a clear URL and use standard HTTP verb to act on it. That's the foundation. A route is the URL that points to a resource. The naming convention is straightforward. Use the plural noun for the collection, like {slash} documents refers to all documents. Add an ID to refer a specific one, like {slash} document 42 is document number 42. You can also nest routes for related resources. For example, {slash} sessions {slash} five {slash} messages refers to all messages inside session five. One rule to remember, routes should be nouns, not verbs. The verb comes from the HTTP method, not the URL. So it's {slash} document, not {slash} get documents or {slash} fetch document. Now, the HTTP verb tells your API what action to perform on the resource. Get is for reading. You are fetching data, not changing anything. Post is for creating something new. Put replaces an existing resource entirely. Patch updates only part of it. Delete removes it. Together, the route and the verb fully describe the action. Get / document means fetch all documents. Post / document means create a new document. Delete / document / 42 means remove document 42. Clean, consistent, and predictable. REST is a great mental model for most of your AI backend, but not all of it. It works really well when you are managing resources like ingesting documents, handling sessions, and managing users. These map cleanly to routes and verbs. But, REST starts to feel awkward when you are dealing with streaming LLM responses, long-running background jobs, or multi-step agentic workflows. These don't fit neatly into the request-response model REST assumes. The good news is that FastAPI handles all of these cases well. We will cover streaming in module six and background task in module five. For now, REST gives you a solid foundation for the majority of your endpoints. To wrap up, REST is a design style, not a strict rule. The core idea is to build your API around resources. Use clear noun-based routes and let HTTP verb define the action. For most of what you will build in this course, REST gives you a clean, predictable structure. In the next video, we will go one level deeper. Path parameters and query parameters. These let you pass data through your routes and filter results, and they are something you will use in almost every endpoint you write. See you there.