8 API Laws of Senior Backend Developer — Transcript

Full transcript

1. 0:00Let's look at eight REST API patterns
2. 0:02that can make your APIs easier to
3. 0:03understand, easier to integrate, and
4. 0:06easier to maintain. Number one, design
5. 0:09around resources, not actions. Here's a
6. 0:12common API design mistake. You see
7. 0:14endpoints like get users, create order,
8. 0:17and delete product. At first, these seem
9. 0:20perfectly understandable, but the URL is
10. 0:22now describing the action, while HTTP is
11. 0:26already designed to describe the action.
12. 0:28A cleaner design is to use users,
13. 0:31orders, and products as resources and
14. 0:32let get, post, and delete describe what
15. 0:35you're doing with them. This becomes
16. 0:37especially useful as the API grows
17. 0:39because the same resource can support
18. 0:40multiple operations without inventing a
19. 0:43different URL for every action. For
20. 0:45example, an order can be retrieved,
21. 0:48replaced, or deleted using the
22. 0:49appropriate HTTP method. The important
23. 0:52idea is simple. Let the URL identify the
24. 0:55resource and let the HTTP method
25. 0:57describe the operation.
26. 0:59Number two, make your URLs predictable.
27. 1:03Here's another thing that looks small
28. 1:04but makes a huge difference. Consistency
29. 1:07in resource naming. Suppose one part of
30. 1:10your API uses user, another uses
31. 1:12customers, and another uses customer
32. 1:14profiles. The individual endpoints might
33. 1:17all work, but now every developer has to
34. 1:20remember the naming rules. A better API
35. 1:23follows a predictable structure.
36. 1:25Collections use consistent resource
37. 1:27names such as users, orders, and
38. 1:29products. And a specific resource can
39. 1:31then be accessed using its identifier.
40. 1:33For multi-word resources, choose one
41. 1:36convention and use it everywhere. The
42. 1:38exact convention matters less than
43. 1:39consistency because a developer
44. 1:41shouldn't have to guess how your API is
45. 1:43structured. A predictable API needs
46. 1:46fewer instructions.
47. 1:47Number three, use HTTP methods for their
48. 1:50actual purpose. Let's say you want to
49. 1:53update a user. One API uses post,
50. 1:56another uses put, another uses patch.
51. 1:59All three might technically work, but
52. 2:02now the client has to understand your
53. 2:03custom rules instead of relying on
54. 2:06standard HTTP semantics. Get should
55. 2:09retrieve data without changing the
56. 2:10resource.
57. 2:12Post is commonly used to create a new
58. 2:13resource or trigger processing that
59. 2:15doesn't fit a straightforward resource
60. 2:17update.
61. 2:18Put is generally used when you're
62. 2:20replacing the representation of a
63. 2:21resource.
64. 2:23Patch is for partial updates. And delete
65. 2:25removes a resource.
66. 2:27There's also an important concept here.
67. 2:29Idempotency.
68. 2:30If you send the same get request five
69. 2:32times, you should get the same kind of
70. 2:34effect as sending it once.
71. 2:36The same general idea applies to put and
72. 2:38delete. You can send the request again
73. 2:40without repeatedly creating new effects.
74. 2:43Post is different. Sending the same
75. 2:45create request twice may create two
76. 2:47resources.
77. 2:48This matters because networks fail,
78. 2:50clients retry, and timeouts happen. Your
79. 2:53API should behave predictably when
80. 2:55requests are repeated. So, don't choose
81. 2:57HTTP methods just because they make the
82. 3:00endpoint work. Choose them according to
83. 3:02their intended semantics. Number four,
84. 3:05make status codes useful.
85. 3:07Here's an API response that causes
86. 3:09problems.
87. 3:10You return 200 OK, but the response body
88. 3:13says that the operation failed because
89. 3:15the product wasn't found. The HTTP
90. 3:18response says success, while the body
91. 3:21says failure. Now, the client has to
92. 3:23inspect two different places to
93. 3:25understand what happened. That's
94. 3:26unnecessary. Use HTTP status codes to
95. 3:29communicate the high-level result. A
96. 3:31successful read might return 200. A
97. 3:34successfully created resource can return
98. 3:36201.
99. 3:38An accepted request that will finish
100. 3:39asynchronously can return 202.
101. 3:42A successful operation without a
102. 3:44response body can return 204.
103. 3:47And errors should communicate what
104. 3:48actually happened. You can use 400 for
105. 3:51an invalid request, 401 when
106. 3:54authentication is missing or invalid,
107. 3:56403 when the client is authenticated but
108. 3:59doesn't have permission, 404 when the
109. 4:01requested resource doesn't exist, 409
110. 4:04when the request conflicts with the
111. 4:05current state, 422 when the request
112. 4:08fails business validation, and 429 when
113. 4:10the client is sending too many requests.
114. 4:13The important thing isn't memorizing
115. 4:15every status code. It's making the
116. 4:17response understandable without
117. 4:18inventing your own error protocol on top
118. 4:21of HTTP.
119. 4:23Use the status code to tell the client
120. 4:24what happened.
121. 4:26Number five, keep errors consistent.
122. 4:29Status codes tell you the category of
123. 4:30the failure, but the client often needs
124. 4:32more information. Compare an error that
125. 4:34simply says something went wrong with a
126. 4:36structured response that provides an
127. 4:38error code, a useful message, and the
128. 4:40status.
129. 4:41The second response is much easier for
130. 4:43both humans and software to work with.
131. 4:46The client can display the message, the
132. 4:48application can react to the error code,
133. 4:50and developers can investigate the
134. 4:52problem. For validation failures, the
135. 4:54API can also return exactly which fields
136. 4:56need attention instead of simply saying
137. 4:59invalid request. The exact format can
138. 5:01vary between systems.
139. 5:03The important thing is that errors
140. 5:04should be structured and predictable.
141. 5:07Your API shouldn't make clients guess
142. 5:08what went wrong. Number six, don't put
143. 5:11everything into the URL path. Here's
144. 5:14another common pattern. You start with a
145. 5:16products endpoint, then you add a
146. 5:18category to the path, then stock status,
147. 5:21then price, then search, then sorting.
148. 5:24Eventually, the URL starts becoming
149. 5:26difficult to manage.
150. 5:27For filtering and optional criteria,
151. 5:30query parameters are usually a better
152. 5:31fit. The path identifies the resource,
153. 5:34while the query parameters refine the
154. 5:36result. But don't use query parameters
155. 5:38to invent actions.
156. 5:40A request that uses a get operation but
157. 5:42adds something like an action equals
158. 5:44delete parameter is confusing because
159. 5:47the HTTP method in the URL no longer
160. 5:51clearly communicate what's happening.
161. 5:53Keep the responsibility clear.
162. 5:55Paths identify resources.
163. 5:57Query parameters refine them. HTTP
164. 6:01methods describe the operation.
165. 6:03Number seven, treat API changes
166. 6:05carefully.
167. 6:06APIs don't stay unchanged forever.
168. 6:09A response that looks perfect today
169. 6:10might need to change 6 months from now.
170. 6:13Maybe you need to add new fields.
171. 6:15Maybe the response structure needs to
172. 6:17change.
173. 6:18Maybe an existing field has the wrong
174. 6:20meaning.
175. 6:21The dangerous part is making a breaking
176. 6:23change without thinking about existing
177. 6:25clients.
178. 6:26Suppose an earlier version returns a
179. 6:28simple price field. And later, you want
180. 6:30to replace it with a richer pricing
181. 6:32structure.
182. 6:33That isn't just another field. The
183. 6:35structure has changed, and existing
184. 6:37clients may break. So, first ask whether
185. 6:40the change actually needs a new version.
186. 6:42Adding a non-required field usually
187. 6:44doesn't require breaking existing
188. 6:46clients.
189. 6:47Changing or removing existing behavior
190. 6:49might. When you do need versioning, make
191. 6:51the strategy obvious and consistent. You
192. 6:54might use a version in the URL, a
193. 6:56request header, or another established
194. 6:58mechanism. The specific strategy matters
195. 7:01less than using one predictable approach
196. 7:03and giving consumers a path to migrate.
197. 7:06Good API evolution means existing
198. 7:08clients don't become collateral damage.
199. 7:11Number eight, keep request and response
200. 7:13formats consistent.
201. 7:15Here's something developers
202. 7:16underestimate. Imagine one endpoint
203. 7:18returns created_at, another returns
204. 7:21created_at, and another returns
205. 7:23created_at.
206. 7:25All three are valid, but now every
207. 7:27client has to remember which convention
208. 7:29applies to which endpoint. The same
209. 7:31problem happens with dates, pagination,
210. 7:33error responses, property names, and
211. 7:36response structures. Pick conventions
212. 7:38and stick to them. For example, use JSON
213. 7:41consistently, choose one naming
214. 7:43convention for JSON properties,
215. 7:45standardize error responses, and make
216. 7:48pagination and filtering work in a
217. 7:49predictable way. The goal is not to
218. 7:51create a giant API rulebook. The goal is
219. 7:54to make the next endpoint look familiar.
220. 7:57When a developer learns how one endpoint
221. 7:58works, they should be able to make
222. 8:00reasonable assumptions about the others.
223. 8:02Consistency is one of the best features
224. 8:04an API can have. And there's one more
225. 8:07thing worth remembering. A lot of
226. 8:09developers focus on whether an API
227. 8:10technically follows REST. That's useful,
228. 8:13but it's not the most important goal.
229. 8:16Your API doesn't become good simply
230. 8:17because it uses GET, POST, PUT, and
231. 8:20DELETE. A good API is one that clients
232. 8:23can understand without constantly
233. 8:24checking documentation.
234. 8:26The resource names make sense. The
235. 8:28methods behave predictably. The status
236. 8:31codes mean something. Errors have a
237. 8:33consistent structure. Filters work the
238. 8:35same way across endpoints, and changes
239. 8:38don't unexpectedly break existing
240. 8:39consumers. That's what makes an API
241. 8:42pleasant to work with. So when you're
242. 8:44designing your next REST API, don't
243. 8:46start by creating endpoints one at a
244. 8:48time. Start by defining the patterns.
245. 8:51How will you name resources? How will
246. 8:53you represent collections? How will
247. 8:55filtering work? Which HTTP methods will
248. 8:59you use? How will errors look? How will
249. 9:02status codes be handled? How will the
250. 9:04API evolve? And what conventions should
251. 9:06every endpoint follow? Because once
252. 9:09those rules are clear, building the API
253. 9:11becomes much easier. A good REST API
254. 9:14doesn't just return the right data. It
255. 9:16makes the right way to use it obvious.