REST APIs - Simply Explained

0:00 You've been using Rest APIs for years without knowing their name. Every time Power Automate grabs your calendar or Copilot studio reads a file, one program is asking another for information. Welcome to the M365 FM podcast, where we explore the people, ideas, and technologies shaping the future of work. Today, we're talking about Rest APIs, the simple pattern behind almost every app you touch. By the end, you'll read a request and understand exactly what comes back. And you'll see why the name rest doesn't mean what it seems to what an API really is. API stands for Application Programming Interface, and the name makes it sound harder than it is. Strip away the label and an API is a set of doorways that one program is allowed to knock on. Each doorway comes with an agreement about what you can ask for and what shape the answer will take.

0:42 The classic comparison is a restaurant. You never walk into the kitchen and you never tell the chef how to cook. You tell the waiter what you want from the menu and the plate comes back to your table. The menu is the agreement, and the waiter is the interface that carries your order between the two sides. The word interface is doing real work there. An interface is simply the shared boundary where two things meet, and it works best when each side keeps its own business private. A website and an API both move information across the internet, but they're built for different readers. A website is designed for your eyes full of colors and buttons and headings. An API is designed for another program so it hands back raw data instead of anything decorative. That difference explains why the agreement matters so much. When two programs share a fixed doorway, neither one has to know how the other works inside.

1:24 You can rebuild the kitchen, swap the chef, and rewrite the recipes without the menu at the table changing at all. Think about why programs need this in the first place. A program can't glance at another program's screen and guess what to do next. It needs a fixed written way to ask for something, and it needs a promise that the reply will arrive in a shape it already knows how to read. That written way is the interface in the name. Salesforce and eBay opened some of the first big web APIs back in the year two thousand, and those calls have been running under the surface ever since. You never noticed them because they were never built for you to see. You've almost certainly used an API today, even if nobody in the room called it that. So an API is really just a doorway with rules, and the rules are what make the exchange predictable.

2:04 Now watch what happens when a request actually walks through that doorway. The round trip. Follow one request from the moment it leaves your app to the moment an answer comes home. The trip has two halves, a request going out, and a response coming back. Both halves follow a shape you can learn in a few minutes. A request carries up to four things. The first is the address, which is the URL pointing to the thing you want. The second is the verb which tells the server what to do with that thing. The third is the headers, a set of extra instructions that travel with the message, including your proof of who you are. The fourth is the body, and it only appears when you're sending data rather than asking for it. The response mirrors all of that. It opens with a three digit status number that says how things went, followed by its own headers. Then comes a body carrying the data you asked for if there's any data to send.

2:46 Microsoft Graph shows this pattern in a form you can actually read. Every graph request follows the same shape, starting with the graph address, then a version, then the resource you want. The version is either v one point oh for production or beta. For things still in preview, send a Get request to that address, followed by users and an email address, and the server answers with a two hundred okay and a body describing that person. Picture the address as the envelope and the body as the letter inside the envelope tells the postal system where the message goes and the letter carries whatever you actually want it to say. The verb rides on the envelope to so the server knows before it opens anything. Whether you're asking a question or handing over new information, notice how little you had to know to follow that you had one address, one verb, and a reply you could read out loud.

3:28 That's the entire rhythm of a rest API, and it repeats for every single call you'll ever make. The verbs, every request carries a verb, and the verb tells the server what kind of action you want the technical name for. It is the HTTP method, and there are only a handful you'll ever meet in normal work. Get asked for information and changes. Nothing at all. Post usually creates something new, like sending an email or adding a comment to a list. Put replaces a whole record with a fresh version of it. Patch updates just part of a record. Delete removes it. Head and options exist too, but therefore checking things behind the scenes and you can go years without touching either one. The verb sits right next to the address, so the pair reads almost like a sentence. Get this thing means show it to me and post. That thing means make it happen.

4:09 Two words matter more than the rest. Here and together they explain a mistake almost everyone makes at some point. A safe method doesn't change anything on the server, so sending it twice costs nothing. An idempotent method gives the same result whether you send it once or five times. Get head. Put. Delete and options are idempotent, while post and patch aren't. That distinction has real bite in your daily tools. If an automation retry is a failed get. Nothing breaks because the same answer simply comes back again. If it retries a failed post. You might create a second email, a second row, or a second order without meaning to. The request looks identical, but the outcome is very different. Hold on to that last idea, because post is also the verb that most often forces a server to ask who you are before it agrees to do anything.

4:51 Resources and addresses. A resource is whatever you're talking about in a given call. It might be a user, an email, a file, or a single row in a table. And the URL is simply where that resource lives on the server. Every address is built from a base that names the service, plus a path that walks down to the exact thing you want. The design idea underneath is clean. Once you see it, the address names the thing, and the verb says what to do with it. So a request often reads like a short sentence get me slash messages means give me my messages and post me slash send. Mail means send an email on my behalf. Microsoft Graph leans on this with a few shortcuts worth knowing. The word me resolves to whoever is signed in so you don't have to look up your own identifier first. Related data hangs off that same path as me slash events, me slash drive, or me slash messages.

5:35 A collection like users holds many of the same thing, and adding an identifier to the end of it points at one specific member of that collection. That's why the same address can describe a whole group or a single person, depending on how far down the path you walk. Sometimes you want to trim the answer without changing the resource itself, and that's what query parameters are for. Add select to a request and the server returns only the fields you name, like display name and city add filter, and it narrows a long list down to a smaller set, such as every user with a particular job title. The addresses feel random at first, but they follow a pattern. You can learn. Once you can read one, you can usually guess the next. Now that you know where to ask, the next question is what comes back? And the answer starts with a number. Status codes. Every response begins with a three digit number, and that number is the server telling you exactly how the request went.

6:20 The first digit carries most of the meaning, so there are only five families to learn. A number starting with one means the request is still in progress. A two means it worked. A three means the answer lives somewhere else. So go look there. A four means the problem is on your side. A five means the problem is on the server side and you did nothing wrong. Here are the ones a beginner actually runs into. Two hundred okay means it worked, and two hundred one means something new was created. Two and four means it worked and there's nothing to send back. While four hundred means your request was malformed. The rest cover the situations you'll hit in a broken flow. Forward one means you didn't prove who you are, and four hundred and three means you proved who you are and still aren't allowed to do this. A four hundred four means nothing lives at that address. A four twenty nine means you're asking too fast and the server wants you to slow down.

7:01 A five hundred means the server broke servers sent numbers instead of sentences for a reason. Another program has to read that reply with no human there to interpret it. So a short fixed code is far easier for software to act on. Your app can check for a two hundred and move on, or catch a four twenty nine and wait quietly before trying again. The pair people mix up most is four hundred one and four hundred three. Authentication is about who you are, while authorization is about what you're allowed to do. A four hundred one means your sign in didn't take, and a four hundred and three means your sign in worked, but your account is missing the permission you need. That one distinction will save you an hour. The next time an automation fails, and the error message tells you nothing useful at all. Json the shared language. When a server sends data back, it usually sends it as Json.

7:42 Jason is a way of writing data as plain text so that any program written in any language can read it. The name stands for JavaScript Object Notation, but you don't need to know JavaScript to use it. The shape is simpler than the name suggests. You write a label, then a value, and you wrap the pair in curly braces. A list of those pairs sits inside square brackets, and you can nest one list inside another as deep as the data goes. That's most of the format, and you can read it out loud without any training at all. A small example makes it concrete. A request for a user might come back with a name label reading John Doe. A city label reading Redmond and a department label reading Help Center. You spot the pattern instantly because the format was written to be read by people as much as by machines. Jason won because it stayed small and readable while the formats around it grew heavy.

8:24 It was formalized as RFC eighty two fifty nine back in December of twenty seventeen, and as the ECMA four hundred and four standard. So almost every modern API treats it as the default way to send data. Learn to read Json, and you can read the answer to nearly any API call, which turns a wall of text into something you can scan in seconds. Proving who you are. None of this works unless the server trusts you, so most requests carry some proof of identity. That proof is called authentication, and it stops just anyone from reading your mail or deleting your files. There are two approaches you'll meet. Most often an API key is a long fixed string you send with every request, and it's easy to start with. The trouble is that it's broad. It rarely expires, and rotating it means touching every place that uses it. OAuth two point oh works differently.

9:05 The app gets a short lived access token, often called a bearer token that stands in for the signed in user and can be revoked when something goes wrong. The difference matters most when a credential leaks. A stolen API key can be reused for as long as it stays valid, which might be forever. A stolen bearer token is short lived by design, so it stops working on its own and gives you a window to cut access off. The surprise is that the credential usually isn't your password. Your app signs you in once, receives a token, and then hands that token to the API on every call so your password never travels with the request. The token is the stand in, and it's built to be thrown away and replaced in a request. This shows up as one extra line in the headers reading authorization, then the word bearer, then the token itself. In the Microsoft Graph example from earlier, that header is exactly what turned a rejected call into a successful one.

9:50 This is also why four hundred one exists in the first place. No valid proof means no answer, and there are no exceptions. Every failed sign in you've ever seen in a flow traces back to this one idea what rest really means. The word rest has an origin story that changes how you hear it. It was coined in two thousand by a computer scientist named Roy Fielding in his doctoral dissertation at the University of California, Irvine. That's the part everyone repeats. What they leave out is what the dissertation was actually about. It wasn't about building web APIs, it was about the web itself. Fielding co-authored the HTTP one point one specification, published in nineteen ninety nine, and his dissertation pulled out the design principles that had guided it. He described an architectural style for connecting documents across the internet, and he named six constraints client and server statelessness, caching, a uniform interface, a layered system, and code on demand.

10:36 Only one chapter of the dissertation even covers rest. Fielding also pushed back on the idea that one style fits everything. He argued that a good designer should pick a style that matches the problem being solved, rather than treating any single approach as a silver bullet for all software. The path from a design essay about the web to the default label for APIs runs straight through soap. Soap was an earlier way to build web services, and it was verbose, XML heavy, and painful to work with. Ruby on Rails dropped its Soap support in two thousand and seven, and developers walked away. They wanted to ride on plain HTTP and rest handed their approach a respectable name. The deeper wrinkle is that strict rest is hypertext driven, which means a real rest API lets you discover every endpoint by following links from a starting point.

11:17 Almost none of the APIs we call RESTful actually do that, and fielding himself pointed it out in two thousand and eight. The name got borrowed, stretched, and pinned to something that was never written for. That's the head fake. And it's the reason this topic finally makes sense. None of this makes the pattern a bad idea. Rest APIs work well for the job most people need, which is letting one program ask another for data over the web. The point is narrower and more useful. The word describes a set of design choices from two thousand, not a set of laws. So nobody is grading your API against a hidden rulebook where you already meet rest. All of this touches the tools on your screen right now, and it goes deeper than you'd expect. Microsoft Graph is the single doorway into Microsoft's cloud, and it follows the exact pattern from this episode.

11:58 It uses an address, a verb, a header proving your identity, and an answer with a number on it. Everything we walked through shows up there in the same order. So the vocabulary matters. Well beyond the podcast. The connectors you click in Power Automate are Rest calls wearing a friendly face? When you drag in an action and fill out a few boxes, the connector builds the request for you, sends it, and hands you back the answer in a neat little card. Copilot studio actions and most PowerShell scripts that talk to Microsoft three hundred sixty five work the same way. Underneath, that's where the vocabulary pays off. In practice, when a flow fails with a four hundred and one, you now know your sign in didn't take. When it fails with a four twenty nine, you know you're asking too fast and you should slow down and retry. The error code stops being noise and turns into a sentence you can act on.

12:39 So the next time a connector simply works, remember what happened underneath one program asked another for something, proved who it was, and got a clean answer back. You don't have to see the request to understand it, and once you understand it, the tools around you stop feeling like magic. A rest API is one program asking another for something, using an address, a verb, some proof of identity, and an answer with a number on it. Json is the shared language, and rest is a name borrowed from a dissertation, not a rule book to memorize. If rest was never written for the APIs we built today, what should we be calling them? Tell me what you'd name it in the comments.