WEBVTT 1 00:00:00.120 --> 00:00:03.240 Welcome to the deep dive. Today, we're jumping into something 2 00:00:03.240 --> 00:00:05.599 that powers so much of our digital world but often 3 00:00:05.639 --> 00:00:08.759 stays hidden, Web API design. Our main guide for this 4 00:00:08.960 --> 00:00:11.279 is the second edition of the Design of Web APIs 5 00:00:11.279 --> 00:00:15.080 by Arnoul Loray. It's described as taking you from well 6 00:00:15.199 --> 00:00:18.160 novice to pro in building APIs that work well, are 7 00:00:18.199 --> 00:00:20.800 easy to use, and importantly aren't a pain to deal with? 8 00:00:20.839 --> 00:00:23.039 So why should you care about this? Simple? Really a 9 00:00:23.079 --> 00:00:26.199 well designed API, it's like a secret startcut to making 10 00:00:26.239 --> 00:00:30.199 things work efficiently, giving users great experiences. A bad one, though, 11 00:00:30.359 --> 00:00:34.439 that's a recipe for frustration, crashes, slow apps, and just 12 00:00:34.560 --> 00:00:37.560 piling up technical problems nobody wants to deal with. Have 13 00:00:37.640 --> 00:00:40.240 you ever struggled with an apro website? Wondered why it 14 00:00:40.280 --> 00:00:42.520 was so slow, or maybe crash or just felt confusing? 15 00:00:42.960 --> 00:00:46.280 Often the root cause, buried deep down is poor API design. 16 00:00:46.399 --> 00:00:48.399 That's exactly right, and the challenge we're really going to 17 00:00:48.479 --> 00:00:51.560 unpack today is figuring out what goes into making an 18 00:00:51.600 --> 00:00:55.280 API that one does the right job, two is actually 19 00:00:55.399 --> 00:00:59.039 user friendly and works well with other systems. Three considers 20 00:00:59.119 --> 00:01:02.479 all the real world constraints like security and performance, and 21 00:01:02.640 --> 00:01:06.239 four is built using a process that keeps getting better. 22 00:01:06.599 --> 00:01:09.560 It's a skill that applies everywhere, whether it's an internal 23 00:01:09.599 --> 00:01:11.480 tool or a huge public platform. 24 00:01:11.560 --> 00:01:14.000 Okay, let's back up a bit. What exactly is a 25 00:01:14.000 --> 00:01:14.680 web API? 26 00:01:15.400 --> 00:01:18.920 Fundamentally, fundamentally, it's a software interface. Think of it as 27 00:01:18.920 --> 00:01:21.120 a way for different applications to talk to each other 28 00:01:21.159 --> 00:01:24.799 over a network, mostly using HTTP, the language of the web. 29 00:01:24.920 --> 00:01:27.239 So when my phone app gets new updates, that's an 30 00:01:27.239 --> 00:01:29.519 API talking to the back end precisely. 31 00:01:29.799 --> 00:01:33.040 Or when different server applications need to coordinate complex tasks 32 00:01:33.079 --> 00:01:36.959 behind the scenes, APIs make that communication possible, and they're 33 00:01:36.959 --> 00:01:40.560 not just single channels. One API can offer many different 34 00:01:40.599 --> 00:01:43.079 operations and many different apps can use that same API. 35 00:01:43.799 --> 00:01:46.840 We should probably also mention the types private for internal use, 36 00:01:47.200 --> 00:01:51.719 partner for specific collaborators, and public APIs for well everyone 37 00:01:52.239 --> 00:01:54.840 and a key thing. Even private APIs might still be 38 00:01:54.879 --> 00:01:57.359 accessible from the Internet. So design and security or just 39 00:01:57.439 --> 00:01:58.319 as crucial there. 40 00:01:58.439 --> 00:02:01.200 Right, which brings us square to why good design is 41 00:02:01.200 --> 00:02:03.719 so critical. Often the best way to see that is 42 00:02:03.760 --> 00:02:06.280 to look at the pain caused by bad design. The 43 00:02:06.319 --> 00:02:10.520 book mentions things like cryptic or inconsistent naming, poor data organization, 44 00:02:10.639 --> 00:02:13.960 maybe missing data or operations we've all been there, right, 45 00:02:14.159 --> 00:02:16.599 I definitely remember hours spent trying to figure out why 46 00:02:16.599 --> 00:02:20.000 a call failed, only getting back a totally unhelpful bad 47 00:02:20.039 --> 00:02:22.319 request error. Just maddening. 48 00:02:22.560 --> 00:02:27.120 Oh. Absolutely, it's a classic developer nightmare. Laurie uses this 49 00:02:27.240 --> 00:02:31.159 brilliant analogy in the book The Kitchen Radar. Imagine a microwave, 50 00:02:31.439 --> 00:02:33.719 but instead of normal controls, it just has one button 51 00:02:34.280 --> 00:02:36.520 bag and you have to hold it down to heat things, 52 00:02:36.840 --> 00:02:38.360 figuring out the timing yourself. 53 00:02:38.599 --> 00:02:41.120 Huh, so you have to become a magnetron expert just 54 00:02:41.159 --> 00:02:42.599 to warm up coffee exactly. 55 00:02:42.960 --> 00:02:46.159 It sounds absurd, but it perfectly mirrors how some poorly 56 00:02:46.199 --> 00:02:51.159 designed APIs force developers to understand obscure internal details, and 57 00:02:51.199 --> 00:02:55.400 the impact is huge. Developers write fragile, complex code, end 58 00:02:55.479 --> 00:02:58.960 users get crashes, confusing errors, maybe workflows that make. 59 00:02:58.919 --> 00:03:02.479 No sense, which leads to frustration, maybe canceling subscriptions or 60 00:03:02.520 --> 00:03:03.759 just switching to a competitor. 61 00:03:03.919 --> 00:03:06.639 Right, and for the company providing the API, it means 62 00:03:06.680 --> 00:03:11.159 rising technical debt, wasted engineer time, production problems, security risks, 63 00:03:11.319 --> 00:03:13.479 even lost revenue. It's bad for everyone. 64 00:03:13.599 --> 00:03:15.360 Okay, So if the kitchen radar is what we want 65 00:03:15.439 --> 00:03:18.360 to avoid, how do we actually build something good? How 66 00:03:18.400 --> 00:03:21.639 does this design process fit into actually building software? 67 00:03:21.840 --> 00:03:25.680 Well? API design sits in that crucial space between figuring 68 00:03:25.719 --> 00:03:27.919 out what's needed and actually starting to write the code. 69 00:03:28.400 --> 00:03:33.319 It's a process. You move through stages like identify API capabilities, 70 00:03:33.599 --> 00:03:36.360 then you design the programming interface. Then you need to 71 00:03:36.400 --> 00:03:39.719 describe it clearly, and finally enrich those design documents. 72 00:03:40.039 --> 00:03:43.080 Okay, and the book breaks this down conceptually into layers. 73 00:03:43.159 --> 00:03:45.800 Yeah, four conceptual layers, each tackling a different aspect of 74 00:03:45.800 --> 00:03:48.599 the problem. The helpful way to think about it. First, 75 00:03:48.960 --> 00:03:52.000 a versatile API design that does the right job. This 76 00:03:52.080 --> 00:03:55.199 is about meeting the real user needs, hiding the messy 77 00:03:55.240 --> 00:03:57.719 internal stuff, and making it usable in ways you might 78 00:03:57.759 --> 00:04:00.879 not even anticipate yet. Think about a so network API. 79 00:04:01.639 --> 00:04:04.240 Maybe today it serves the mobile and web apps, but 80 00:04:04.280 --> 00:04:07.360 a well designed versatile one could potentially power a smart 81 00:04:07.400 --> 00:04:10.400 fridge integration tomorrow without needing a rewrite. 82 00:04:10.599 --> 00:04:13.120 Interesting future proofing, almost what's next. 83 00:04:13.319 --> 00:04:17.000 Second layer, an API design that is user friendly and interoperable, 84 00:04:17.279 --> 00:04:20.360 making it easy to understand, easy to use, and ensuring 85 00:04:20.360 --> 00:04:24.199 it plays nicely with other systems. Common sense, but crucial 86 00:04:24.279 --> 00:04:29.120 makes sense. Third third, an API design that considers constraints. 87 00:04:29.720 --> 00:04:33.079 This is where you really integrate things like security performance, 88 00:04:33.439 --> 00:04:36.399 the specific context it operates in, and how you'll handle 89 00:04:36.439 --> 00:04:40.319 future changes. And the final layer, finally, a reasoned and 90 00:04:40.439 --> 00:04:44.399 continuously improving API design process. This is about how you 91 00:04:44.439 --> 00:04:48.199 make decisions consistently based on good principles and always looking 92 00:04:48.199 --> 00:04:49.120 for ways to improve. 93 00:04:49.279 --> 00:04:52.720 Okay, let's dive into that first layer. Then identifying capabilities. 94 00:04:52.720 --> 00:04:53.879 Where do you even start? 95 00:04:54.120 --> 00:04:57.879 You start by analyzing the user needs. This often begins 96 00:04:57.920 --> 00:05:00.240 pretty vague, like we need a social network, you. 97 00:05:00.199 --> 00:05:02.600 Know, right, very high level exactly. 98 00:05:02.519 --> 00:05:04.360 But you need to quickly get more specific. What does 99 00:05:04.360 --> 00:05:07.600 that actually mean for users? Maybe it's allow users to 100 00:05:07.639 --> 00:05:11.000 tag friends in a photo. The key is expressing these 101 00:05:11.040 --> 00:05:14.319 needs in plane language first, something everyone involved can understand. 102 00:05:14.560 --> 00:05:17.759 So how do you break those big needs down systematically? 103 00:05:18.000 --> 00:05:21.680 Decomposition is key breaking down those use cases into small, 104 00:05:21.759 --> 00:05:25.160 manageable steps. The book introduces a tool called the API 105 00:05:25.279 --> 00:05:29.680 Capabilities Canvas for this. You work through it twice. Essentially, First, 106 00:05:29.759 --> 00:05:31.879 you map out the happy path, the way things should 107 00:05:31.879 --> 00:05:34.959 work ideally, the normal flow right. Then you go back 108 00:05:34.959 --> 00:05:38.279 and figure out all the alternative paths. There are edge cases, 109 00:05:38.759 --> 00:05:42.439 and importantly, the failure scenarios what happens when things go wrong, 110 00:05:42.959 --> 00:05:46.959 and doing this often reveals overlaps, like the step upload 111 00:05:47.000 --> 00:05:49.920 of photo might be needed for sharing a status and 112 00:05:50.000 --> 00:05:54.399 for changing your profile picture, same underlying capability, different context. 113 00:05:54.560 --> 00:05:57.519 Okay, so you've identified these capabilities, how does that translate 114 00:05:57.519 --> 00:06:01.480 into the actual interface a developer interact with the programming interface? 115 00:06:01.720 --> 00:06:06.240 Those capabilities generally map onto two core concepts, resources and actions. 116 00:06:06.759 --> 00:06:09.000 A resource is like a now a high level concept 117 00:06:09.040 --> 00:06:12.319 like product, user, order and actions are the verbs what 118 00:06:12.399 --> 00:06:16.120 you can do to those resources get product, create, order, update, 119 00:06:16.199 --> 00:06:18.079 user search products. 120 00:06:17.560 --> 00:06:20.279 And how are those represented in a typical web API 121 00:06:20.480 --> 00:06:21.240 using HTTP. 122 00:06:21.480 --> 00:06:24.439 That's where the standard AGTP methods come in. Get to retrieve, 123 00:06:24.600 --> 00:06:28.000 post to create, put to replace, patch to partially update, 124 00:06:28.160 --> 00:06:31.839 and delete to remove. You combine these methods with resource paths, 125 00:06:31.879 --> 00:06:35.160 which are like addresses for your resources products for the 126 00:06:35.160 --> 00:06:37.480 collection products one, two, three for a specific one. 127 00:06:37.600 --> 00:06:41.480 So the path structure shows relationships like users, four, five, six, 128 00:06:41.600 --> 00:06:42.680 orders exactly. 129 00:06:42.959 --> 00:06:47.040 It describes hierarchy. But, and this is crucial, the paths 130 00:06:47.040 --> 00:06:50.720 should not directly mirror how your data is stored internally. 131 00:06:51.199 --> 00:06:53.920 You want to hide the provider's perspective and focus on 132 00:06:53.959 --> 00:06:54.959 the consumer's needs. 133 00:06:55.079 --> 00:06:58.800 That keeps it flexible, right decoupling. Now, when a developer 134 00:06:58.839 --> 00:07:02.720 makes a request, where does the input data actually go? 135 00:07:02.720 --> 00:07:07.000 Good question? There are standard places within an HTTPU request. 136 00:07:07.360 --> 00:07:10.240 Path parameters are usually for identifiers like that product's one 137 00:07:10.279 --> 00:07:12.439 twenty three. The one to twenty three is a path parameter. 138 00:07:12.480 --> 00:07:13.160 Okay, it makes sense. 139 00:07:13.240 --> 00:07:16.000 Query parameters live after the question mark in the URL. 140 00:07:16.199 --> 00:07:20.399 They're great for things that modify the request like filter, status, published, sorting, 141 00:07:20.480 --> 00:07:22.360 or pagination in any ear, you don't want to force 142 00:07:22.399 --> 00:07:24.560 these into the path as they're often optional. 143 00:07:24.680 --> 00:07:25.519 Got it? What else? 144 00:07:25.680 --> 00:07:29.959 Headers carry metadata about the request itself, things like authentication tokens, 145 00:07:30.000 --> 00:07:36.279 authorization bearer, or specifying the content type being sent, content type, dot, application, adjacent. 146 00:07:36.079 --> 00:07:38.480 And the main data for creating something new. 147 00:07:38.720 --> 00:07:41.839 That usually goes in the request body, especially for post 148 00:07:41.959 --> 00:07:45.560 put and patthch requests, where you're sending a representation of 149 00:07:45.600 --> 00:07:46.120 the resource. 150 00:07:46.279 --> 00:07:48.839 Okay, so that's input. What about the output? How does 151 00:07:48.839 --> 00:07:50.800 the API tell the consumer what happened? 152 00:07:51.000 --> 00:07:54.639 Primarily through HTDP status codes, those familiar three digit. 153 00:07:54.560 --> 00:07:56.879 Numbers like two hundred to ok or four or four 154 00:07:57.199 --> 00:07:58.279 not found exactly. 155 00:07:58.360 --> 00:08:02.120 They fall into classes two XX means success. Four x 156 00:08:02.199 --> 00:08:04.839 means the client messed up, bad input, not authorized, et cetera. 157 00:08:05.079 --> 00:08:07.519 Five xx means something went wrong on the server side. 158 00:08:07.800 --> 00:08:10.639 Common success codes include two oh one created when you 159 00:08:10.639 --> 00:08:13.199 successfully make a new resource, or two oho four to 160 00:08:13.199 --> 00:08:16.480 no content after a successful deletion where there's nothing to return, 161 00:08:16.560 --> 00:08:19.560 and errors four hundred to bout amount. Bad request is 162 00:08:19.600 --> 00:08:22.600 common for invalid input, four to one, unauthorized, four oh 163 00:08:22.639 --> 00:08:25.160 three forbidden, four hundred for four and not found. They 164 00:08:25.240 --> 00:08:29.759 all signal specific client side issues. Crucially, successful responses often 165 00:08:29.800 --> 00:08:32.720 return data in the response body, and for creations a 166 00:08:32.759 --> 00:08:35.200 two oh one you should usually include a location header 167 00:08:35.399 --> 00:08:37.679 pointing to the URL of the newly created resource. 168 00:08:37.840 --> 00:08:40.200 Makes sense, Let's shift to the data itself. How do 169 00:08:40.240 --> 00:08:42.679 you actually define the structure of the information being passed 170 00:08:42.679 --> 00:08:43.320 back and forth. 171 00:08:43.440 --> 00:08:46.919 That's where data modeling comes in, usually using Jason's schema 172 00:08:47.000 --> 00:08:50.399 within an open API specification. It gives you a formal 173 00:08:50.440 --> 00:08:54.879 way to describe the data structure, types, constraints, everything. 174 00:08:54.799 --> 00:08:57.480 And the book suggests a particular approach. 175 00:08:57.600 --> 00:08:59.960 Yeah. It emphasizes the idea of starting with a theore, 176 00:09:00.000 --> 00:09:04.000 medical or complete resource model. Think of your product resource 177 00:09:04.039 --> 00:09:06.960 to find everything it could possibly contain all the details 178 00:09:07.000 --> 00:09:10.559 the maximal view. Right then that complete model becomes the 179 00:09:10.600 --> 00:09:13.840 source for deriving other more specific models you'll actually use 180 00:09:13.840 --> 00:09:17.519 in the API, like summarize models for when you return 181 00:09:17.559 --> 00:09:20.720 a list. You don't need every detail to summary minimal 182 00:09:20.759 --> 00:09:23.639 models that might just contain the ID maybe for linking 183 00:09:23.679 --> 00:09:28.559 between resources. Creation models for PST requests often a subset 184 00:09:28.600 --> 00:09:31.559 of the full model only the fields needed to create it. 185 00:09:31.679 --> 00:09:33.840 Same for put replacement. 186 00:09:33.440 --> 00:09:36.039 And PCCh for updates. 187 00:09:35.840 --> 00:09:39.279 Exactly, modification models for PTH, where typically all fields are 188 00:09:39.320 --> 00:09:42.440 optional because you're only changing some things. This approach brings 189 00:09:42.480 --> 00:09:45.440 a lot of consistency. You're not defining similar structures over 190 00:09:45.480 --> 00:09:46.120 and over again. 191 00:09:46.320 --> 00:09:50.080 That leads nicely into data user friendliness. It's not just 192 00:09:50.159 --> 00:09:52.799 about structure, but the content of the data, right. 193 00:09:52.720 --> 00:09:56.399 Absolutely, it's about selecting data that's genuinely relevant and helpful 194 00:09:56.440 --> 00:09:59.279 to the consumer, not just dumping everything from your database. 195 00:10:00.000 --> 00:10:04.919 The idea here is providing supporting data or even process data. 196 00:10:04.960 --> 00:10:06.039 What's an example of that. 197 00:10:06.559 --> 00:10:09.320 The book gives a great banking API example. Instead of 198 00:10:09.360 --> 00:10:12.039 just giving the raw count balance and the overdraft limit 199 00:10:12.279 --> 00:10:15.960 and forcing the consumer to calculate if a purchase is possible. 200 00:10:15.600 --> 00:10:18.840 You could provide a calculated safe to spend amount exactly 201 00:10:19.120 --> 00:10:22.919 that directly answers the user's likely question, reduces the chance 202 00:10:22.960 --> 00:10:25.919 of errors on their side, and makes the API much 203 00:10:25.960 --> 00:10:26.759 easier to use. 204 00:10:27.320 --> 00:10:28.840 It's about anticipating needs. 205 00:10:29.240 --> 00:10:32.320 That's smart. What else contributes to user friendly data? 206 00:10:32.480 --> 00:10:36.200 Using well known or standard identifiers whenever possible, Like use 207 00:10:36.240 --> 00:10:38.200 an IBAND for a bank account if that's the standard. 208 00:10:38.240 --> 00:10:40.480 Don't just expose your internal database ID. 209 00:10:40.559 --> 00:10:43.039 Makes sense less look up needed right, and use. 210 00:10:42.960 --> 00:10:45.919 Human readable codes instead of account type one. Use account 211 00:10:45.960 --> 00:10:50.519 type checking. It's immediately understandable, and of course, be super 212 00:10:50.559 --> 00:10:53.840 consistent with your atomic data types and formats. Always use 213 00:10:53.879 --> 00:10:56.039 ISO eighty six to ZHO one for dates and times 214 00:10:56.080 --> 00:10:57.519 for example, no surprises. 215 00:10:57.559 --> 00:11:01.080 Okay, And how about organizing the data within a response? 216 00:11:01.279 --> 00:11:02.360 Structuring it well? 217 00:11:02.519 --> 00:11:06.600 Good structure is key. Use objects to group related feels together, 218 00:11:06.879 --> 00:11:09.759 like instead of overdraft limit and overdraft, use floating around 219 00:11:10.039 --> 00:11:12.279 group them in an overdraft facility. 220 00:11:11.799 --> 00:11:13.440 Object keeps things tidy. 221 00:11:13.600 --> 00:11:17.759 Yeah, and use a raise for lists of similar items, 222 00:11:17.840 --> 00:11:20.120 like a balance's array if an account can have multiple 223 00:11:20.120 --> 00:11:24.200 currency balances. But there's a big caution here. Avoid embedding 224 00:11:24.279 --> 00:11:28.159 large lists directly within a main resource response, especially if 225 00:11:28.159 --> 00:11:30.519 those lists might need filtering or pagination. 226 00:11:30.440 --> 00:11:33.679 Like putting all of a user's transaction history inside the 227 00:11:33.720 --> 00:11:35.200 main user object exactly. 228 00:11:35.279 --> 00:11:37.919 That's usually a bad idea. If you need to get transactions, 229 00:11:38.240 --> 00:11:41.440 provide a dedicated operation like users one, two, three transactions 230 00:11:41.679 --> 00:11:45.679 that supports pagination and filtering properly. Don't overload the primary resource. 231 00:11:45.759 --> 00:11:47.480 That makes a lot of sense for performance too. 232 00:11:47.799 --> 00:11:51.360 Absolutely, and the golden rule overarting all of this data 233 00:11:51.399 --> 00:11:56.279 design is consistency, naming, conventions, data types. How you structure 234 00:11:56.320 --> 00:11:59.559 objects in a raise keep it consistent across the entire API. 235 00:12:00.080 --> 00:12:03.720 That predictability makes the API dramatically easier and faster for 236 00:12:03.759 --> 00:12:05.159 developers to learn and use. 237 00:12:05.519 --> 00:12:08.440 Right, Okay, let's pivot to constraints. Starting with a big 238 00:12:08.440 --> 00:12:13.519 one security, How does API designed influence security massively? 239 00:12:13.799 --> 00:12:16.039 Security isn't something you bolt on at the end. It 240 00:12:16.080 --> 00:12:18.000 needs to be baked into the design choices you make 241 00:12:18.000 --> 00:12:21.240 from the start. Your design is part of your security posture. 242 00:12:21.360 --> 00:12:22.919 So how do you design for security? 243 00:12:23.039 --> 00:12:27.120 A fundamental principle is minimizing the API surface area. Only 244 00:12:27.200 --> 00:12:30.879 expose the operations and the data that are absolutely necessary. 245 00:12:31.039 --> 00:12:34.159 Really challenge requests for sensitive data. Do we really need 246 00:12:34.200 --> 00:12:37.399 to expose the user's exec GPS coordinates or their phone number? 247 00:12:37.559 --> 00:12:39.480 If so, why and if you do need it. 248 00:12:39.320 --> 00:12:41.720 Maybe can transform it, perhaps return a city or region 249 00:12:41.759 --> 00:12:45.679 instead of precise coordinates, or maybe split very sensitive operations 250 00:12:45.679 --> 00:12:49.080 off into a separate API that has much tighter access controls. 251 00:12:49.519 --> 00:12:51.000 Less exposure means less risk. 252 00:12:51.320 --> 00:12:54.279 Speaking of access control, how does that work in API design? 253 00:12:54.360 --> 00:12:55.639 You mentioned scopes earlier. 254 00:12:55.919 --> 00:12:59.720 Yes, scopes are a common mechanism for authorization. They define permissions. 255 00:13:00.200 --> 00:13:02.320 You might have a red profile scope and a separate 256 00:13:02.399 --> 00:13:05.720 update profile scope, or maybe a transfer money scope. 257 00:13:05.799 --> 00:13:08.759 So the API consumer requests certain scopes and the API 258 00:13:08.919 --> 00:13:11.360 checks if they have them before allowing an operation. 259 00:13:11.399 --> 00:13:14.159 Exactly, and scopes can be defined that different levels of 260 00:13:14.200 --> 00:13:17.960 granularity per operation, per resource type, maybe even based on 261 00:13:18.000 --> 00:13:21.200 the specific user role or the application making the call. 262 00:13:21.639 --> 00:13:23.240 Depends on your security requirements. 263 00:13:23.320 --> 00:13:27.480 Okay, what about protecting the data itself? Data integrity? 264 00:13:28.000 --> 00:13:32.679 Several design aspects contribute here. First, using HTTP methods correctly 265 00:13:33.159 --> 00:13:36.200 get should be safe, no side effects. Put in delete 266 00:13:36.200 --> 00:13:39.200 should be idempatant. Running them multiple times as the same 267 00:13:39.200 --> 00:13:40.240 effect as running them. 268 00:13:40.080 --> 00:13:43.639 Once prevents accidental double charges or double deletions. If a 269 00:13:43.720 --> 00:13:45.440 request is retried precisely. 270 00:13:45.960 --> 00:13:49.519 You can also prevent malicious or accidental request replays by 271 00:13:49.559 --> 00:13:53.879 requiring an adempotency key header. For non adempitent operations like PFOST, 272 00:13:54.200 --> 00:13:56.799 the server uses this key to ensure it only processes 273 00:13:56.840 --> 00:14:00.840 the request once AH and for updates. Condition updates are vital. 274 00:14:01.000 --> 00:14:04.120 Imagine two users trying to update the same customer record 275 00:14:04.240 --> 00:14:04.960 at the same time. 276 00:14:05.240 --> 00:14:09.000 One might overwrite the other's changes without realizing it right. 277 00:14:09.440 --> 00:14:12.320 Using E tag hitters, which represent the version of the 278 00:14:12.360 --> 00:14:16.399 resource and if match hitters, which say only perform this 279 00:14:16.480 --> 00:14:18.759 update if the E tag matches what I last saw 280 00:14:19.639 --> 00:14:22.039 prevents this lost update problem. 281 00:14:22.240 --> 00:14:26.039 Got it? That seems really important for data consistency. What 282 00:14:26.120 --> 00:14:28.440 about handling errors securely? 283 00:14:28.840 --> 00:14:32.519 Yes, secure air handling is crucial. You need to give feedback, 284 00:14:32.840 --> 00:14:35.159 but not too much information that could help an attacker. 285 00:14:35.759 --> 00:14:40.799 Use standard machine readable error formats like problem details for httpapis. 286 00:14:41.159 --> 00:14:44.799 This provides structure type, title, status, detail, instant It. 287 00:14:44.840 --> 00:14:48.799 Avoid generic unhelpful messages like just error definitely. 288 00:14:48.320 --> 00:14:51.279 But also return all validation errors at once if possible. 289 00:14:51.399 --> 00:14:54.279 Don't make the consumer fix one thing, resubmit find another error. 290 00:14:54.360 --> 00:14:56.440 Fix that. It's incredibly frustrating. 291 00:14:56.519 --> 00:14:59.080 Yeah, that back and forth is terrible. Any other security 292 00:14:59.080 --> 00:14:59.679 pitfalls and. 293 00:14:59.679 --> 00:15:04.440 Design one big one. Sensitive data in URLs. Even with 294 00:15:04.600 --> 00:15:09.759 HTTPS URLs, paths and query parameters can leak. They might 295 00:15:09.840 --> 00:15:13.039 end up in browser history, server logs, referra headers, So. 296 00:15:13.039 --> 00:15:15.320 Putting a password or credit card number in a query 297 00:15:15.360 --> 00:15:17.679 parameter is a definite no. 298 00:15:17.519 --> 00:15:20.559 No absolutely for anything sensitive, especially if it's being used 299 00:15:20.559 --> 00:15:24.720 for searching or filtering. Strongly, consider using a post request 300 00:15:24.759 --> 00:15:28.000 and putting these sensitive data securely in the request body instead. 301 00:15:28.120 --> 00:15:32.279 Good tip. Okay, let's switch from security to another key constraint. Efficiency. 302 00:15:32.679 --> 00:15:33.759 Why is this so important? 303 00:15:33.919 --> 00:15:38.399 Efficiency benefits everyone? For consumers, it means faster apps, less 304 00:15:38.399 --> 00:15:42.480 battery drain on mobile, lower data usage. For the API provider, 305 00:15:42.519 --> 00:15:46.480 it means lower server costs, less strain on infrastructure, better scalability. 306 00:15:46.840 --> 00:15:48.759 Small efficiencies can save a lot of money at. 307 00:15:48.679 --> 00:15:51.159 Scale, So how do you design for efficiency? Caching seems 308 00:15:51.200 --> 00:15:51.960 like an obvious one. 309 00:15:52.000 --> 00:15:55.639 Cashing is huge. Using standard HTTP caching headers like cash 310 00:15:55.639 --> 00:15:59.799 control tells downstream caches, browsers, CDNs proxies how long they 311 00:15:59.799 --> 00:16:01.159 can use a response without. 312 00:16:01.000 --> 00:16:03.960 Asking again, saves bandwidth and reduces load massively. 313 00:16:04.440 --> 00:16:07.519 And even better is using conditional requests with ETag and 314 00:16:07.600 --> 00:16:10.759 if none match, the client sends the ETag it has 315 00:16:10.799 --> 00:16:13.919 for a resource. If the resource hasn't changed on the server, 316 00:16:14.320 --> 00:16:17.080 the server just replies with a tiny three to four 317 00:16:17.360 --> 00:16:21.360 not modified response without sending the data. Again super efficient. 318 00:16:21.559 --> 00:16:23.879 Nice. What about reducing the end of data sent in 319 00:16:23.919 --> 00:16:24.639 the first place? 320 00:16:24.840 --> 00:16:29.279 Several techniques we mentioned Resource model selection earlier let consumers 321 00:16:29.320 --> 00:16:31.159 ask for a summarized view if they don't need all 322 00:16:31.200 --> 00:16:35.559 the details. Field selection is another, allowing consumers to explicitly 323 00:16:35.600 --> 00:16:40.080 request only the fields they need, like dot field's name. Balance, 324 00:16:40.360 --> 00:16:41.960 Why send data they're just going to ignore? 325 00:16:42.039 --> 00:16:42.519 Good point. 326 00:16:42.720 --> 00:16:45.320 Also look for redundant data. If the same piece of 327 00:16:45.320 --> 00:16:48.600 information appears in many different responses, maybe centralize it in 328 00:16:48.639 --> 00:16:52.279 its own resource or operation, and definitely prefer partial updates 329 00:16:52.360 --> 00:16:56.440 using PTCH over full replacements with pet when possible, Sending 330 00:16:56.480 --> 00:16:58.720 only the changed fields is much more efficient than sending 331 00:16:58.759 --> 00:17:00.159 the entire resource representation. 332 00:17:00.240 --> 00:17:03.360 Again right, the book mentioned two types of PTCH. 333 00:17:03.639 --> 00:17:07.640 Yes, Jason merge patch is simpler, basically merging the provided 334 00:17:07.720 --> 00:17:11.279 JSON into the existing resource. Jason patch is more powerful, 335 00:17:11.559 --> 00:17:15.960 using explicit operations like ad remove, replace targeted at specific 336 00:17:16.000 --> 00:17:18.759 parts of the Jason document. It's better for complex updates, 337 00:17:18.880 --> 00:17:20.160 especially involving a raise. 338 00:17:20.359 --> 00:17:23.839 Okay, what about handling large lists of items efficiently? 339 00:17:24.119 --> 00:17:27.400 Pagination is essential, don't try to return thousands of items 340 00:17:27.440 --> 00:17:29.440 in one go. Break it into pages. 341 00:17:29.720 --> 00:17:31.279 Index based or cursor based. 342 00:17:31.559 --> 00:17:34.680 Both have pros and cons Cursor based is generally more 343 00:17:34.759 --> 00:17:38.400 robust against data changing while you're paginating. But the critical 344 00:17:38.400 --> 00:17:41.640 design decision here is a default page size. The book 345 00:17:41.640 --> 00:17:44.880 warns against huge defaults like ten thousand that can hammer 346 00:17:44.920 --> 00:17:48.039 your database and the network. Choose a sensible default, maybe 347 00:17:48.039 --> 00:17:51.240 twenty fifty or one hundred, and let consumers request more 348 00:17:51.279 --> 00:17:52.240 if they really need it. 349 00:17:52.359 --> 00:17:54.880 Sensible advice any other efficiency boosters. 350 00:17:55.160 --> 00:17:58.079 Bulk operations can be great. Instead of making one hundred 351 00:17:58.079 --> 00:18:00.759 separate API calls to create one hundred acas ounce, allow 352 00:18:00.799 --> 00:18:02.759 a consumer to send a single request with all one 353 00:18:02.799 --> 00:18:04.799 hundred much less network overhead. 354 00:18:04.920 --> 00:18:07.960 But how do you handle errors in bulk operations? If 355 00:18:08.000 --> 00:18:08.680 one fails? 356 00:18:09.000 --> 00:18:11.359 That's the key design choice. Is it all or nothing 357 00:18:11.599 --> 00:18:14.920 one failure fails the whole batch, or do you process 358 00:18:14.960 --> 00:18:18.839 each one individually and return a mixed result. The each 359 00:18:18.920 --> 00:18:22.720 TTP two O seven multi status response code is often 360 00:18:22.799 --> 00:18:26.039 used for mixed results indicating success or failure for each 361 00:18:26.079 --> 00:18:26.799 item in the batch. 362 00:18:26.960 --> 00:18:29.799 Okay, and finally managing usage. 363 00:18:29.440 --> 00:18:32.960 Right rate limiting. You need to control how frequently consumers 364 00:18:32.960 --> 00:18:36.160 can call your API to protect your infrastructure from overload, 365 00:18:36.359 --> 00:18:40.480 whether accidental or malicious, and crucially be transparent about it. 366 00:18:40.960 --> 00:18:43.920 Use standard headers like rate limit limit, rate limit, remaining, 367 00:18:44.000 --> 00:18:47.039 rate limit reset, or the older X rate limit versions 368 00:18:47.319 --> 00:18:49.799 so consumers know the rules and can adjust their behavior. 369 00:18:50.000 --> 00:18:53.759 Makes sense. Protect yourself, but let users know the limits exactly. 370 00:18:53.960 --> 00:18:58.079 It's about fairness and stability. Now, beyond security and efficiency, 371 00:18:58.480 --> 00:19:01.279 good API design has a consider the broader context that 372 00:19:01.400 --> 00:19:04.279 operates in What are the specific needs or constraints of 373 00:19:04.319 --> 00:19:05.480 this particular situation. 374 00:19:05.640 --> 00:19:08.240 Can you give some examples of these contextual constraints? 375 00:19:08.440 --> 00:19:11.000 Sure? Think about file handling. If you need to upload 376 00:19:11.000 --> 00:19:13.920 a file along with some metadata, multipart form data is 377 00:19:13.960 --> 00:19:16.799 a standard way or maybe Base sixty four encoding for 378 00:19:16.839 --> 00:19:20.160 small files embedded in JSON, though that increases size. 379 00:19:20.200 --> 00:19:23.240 What about really big files, uploading videos or something. 380 00:19:23.319 --> 00:19:26.319 Yeah, for large files, hitting your main API gateway might 381 00:19:26.359 --> 00:19:29.279 not be efficient or even possible due to size limits. 382 00:19:29.799 --> 00:19:32.640 A common pattern is to use sign URLs your API 383 00:19:32.720 --> 00:19:36.480 generates a temporary, secure URL, maybe pointing to cloud storage 384 00:19:36.519 --> 00:19:38.880 like S three gives it to the client, and the 385 00:19:38.920 --> 00:19:42.480 client uploads or downloads directly from storage by passing your 386 00:19:42.519 --> 00:19:44.720 main API infrastructure for the bulk transfer. 387 00:19:44.960 --> 00:19:47.960 Ah, that's clever, offloading the heavy lifting. What else? 388 00:19:48.119 --> 00:19:52.400 Event notification Sometimes the consumer needs to know when something 389 00:19:52.440 --> 00:19:55.920 happens immediately without constantly asking the API anything new. 390 00:19:56.000 --> 00:19:58.519 Yet that's pulling right can be inefficient. 391 00:19:58.799 --> 00:20:02.279 Very The alternative is web hoooks. The consumer provides a URL, 392 00:20:02.599 --> 00:20:05.880 and your API calls their URL proactively whenever is specific 393 00:20:05.920 --> 00:20:08.960 event occurs, like a new order, place to transaction completed. 394 00:20:09.319 --> 00:20:11.559 Standard formats like cloud vents help make these web hoook 395 00:20:11.559 --> 00:20:13.799 payloads consistent and understandable. 396 00:20:13.240 --> 00:20:16.319 So the information flows the other way when needed. What 397 00:20:16.400 --> 00:20:18.720 about tasks that just take a long time. 398 00:20:18.640 --> 00:20:22.079 Long running operations, Yeah, like starting a complex data analysis 399 00:20:22.160 --> 00:20:26.680 job or a simulation. The initial API call might return immediately, 400 00:20:26.720 --> 00:20:29.839 maybe for the status urrol. Then the client has two options, 401 00:20:30.480 --> 00:20:35.079