The Hitchhiker's Guide for an Amazing API with TypeScript

1. TS Hitchhiker's Guide For an amazing API design
2. $ whoami_ {twitter, youtube, linkedin…}.lsantos.dev founding engineer_ hello@lsantos.dev
3. whats and hows first and foremost, what's this all about - General best practices - Using TypeScript in APIs - Going Beyond TypeScript
4. DISCLAIMER
5. BUT
6. there are three_ rules of a sensible API design
7. Be consistent
8. response schemas_
9. response schemas_ response schemas_
10. response schemas ❌ response schemas_
11. response schemas ✅ ❌ response schemas_
12. response schemas response schemas_
13. response schemas cannot read property length of undefined response schemas_
14. response schemas response schemas_
15. bottom line
16. dynamic keys_
17. dynamic keys dynamic keys_
18. dynamic keys dynamic keys_
19. dynamic keys dynamic keys_
20. dynamic keys dynamic keys_
21. dynamic keys dynamic keys_
22. dynamic keys dynamic keys_
23. bottom line
24. output consistency outputs should be predictable - Same structure if possible - Same casing - Same building logic
25. class-based responses
26. final thoughts on consistency - Use sensible endpoint names - Use sensible HTTP verbs
27. once upon a time in a company I worked for https://api.mycompanydomain.com/v1/getOffers
28. once upon a time in a company I worked for POST https://api.mycompanydomain.com/v1/getOffers
29. once upon a time in a company I worked for POST https://api.mycompanydomain.com/v1/getOffers Returned a list of cards which we had to fetch another endpoint to get the offers
30. naming - no verbs (like /enable) - plural if list - singular if resource - kebab-cased is more readable - don't include verb (like /getOffers) - if subresource use /parent/:id/resource
31. verbs if you haven't please read RFC2616 (section 9) - GET ➡ fetching resources - POST ➡ creating things - PUT ➡ update the WHOLE resource - PATCH ➡ update PART of the resource - DELETE ➡ delete resource (duh)
32. Be descriptive
33. correct HTTP status codes yes, there's life beyond 200, 400 and 500
34. status codes cheat sheet: the good - Deleted something ➡ 204 - Created something ➡ 201 - Will do something ➡ 202 - All others ➡ probably 200
35. the http status code cheat sheet: the bad - Validation failed ➡ 422 - Unauthorized ➡ 401 - Forbidden (know who you are, but you can't do it) ➡ 403 - Not found ➡ 404 - Duplicate ➡ 409 - Something else you depend on failed ➡ 424 - Rate limiting ➡ 429 - Timeout ➡ 408 - Too many stuff on body ➡ 413 - Didn't implement that method ➡ 405 - and so on… Avoid 400
36. the http status code cheat sheet: the ugly - Server messed up ➡ 500 - Future implementation ➡ 501 - Routing issues ➡ 502, 503, 504 (depending on the case)
37. error standardization
38. error standardization
39. error standardization
40. OpenAPI the best thing to have, terrible to maintain
41. spec as code: from spec to code 📝 ➡ 👾
42. spec as code: from code to spec 📝 ⬅ 👾
43. you don't have to do it from scratch
44. you don't have to do it from scratch
45. you don't have to do it from scratch
46. Be deterministic
47. schema driven development kneel before Zod - define once, derive everywhere - single source of truth - built-in error handling
49. schema driven development
50. schema driven development
51. schema driven development
52. global configs, local overrides schematize your envs - environment validation - configuration always present - intellisense - better security
53. global configs
54. global configs Use the Node native --env-file flag
55. final quick tips
56. let it break, handle errors globally
57. let it break, handle errors globally
58. separation of concerns
59. separation of concerns 󰠤 User
60. separation of concerns 🎨 Presentation layer > validation > calls services > formats responses 󰠤 User
61. separation of concerns 🎨 Presentation layer > validation > calls services > formats responses 󰠤 User ⚙ Service Layer > interfaces with other services > interfaces with one repository > external business logic
62. separation of concerns 🎨 Presentation layer > validation > calls services > formats responses 󰠤 User ⚙ Service Layer > interfaces with other services > interfaces with one repository > external business logic 💽 Data Layer > interacts with the database > external apis > receives domain objects > returns domain objects > never errors > can only be called by services
63. separation of concerns 🎨 Presentation layer > validation > calls services > formats responses 󰠤 User ⚙ Service Layer > interfaces with other services > interfaces with one repository > external business logic 📄 Domain bus > individual entities > entity business logic > present in all layers > error definitions 💽 Data Layer > interacts with the database > external apis > receives domain objects > returns domain objects > never errors > can only be called by services
64. separation of concerns 🎨 Presentation layer > validation > calls services > formats responses 󰠤 User ⚙ Service Layer > interfaces with other services > interfaces with one repository > external business logic 📄 Domain bus > individual entities > entity business logic > present in all layers > error definitions 💽 Data Layer > interacts with the database > external apis > receives domain objects > returns domain objects > never errors > can only be called by services
65. refs_ - https://lsantos.dev/rfc2616 (definition of HTTP methods) - https://lsantos.dev/patch-method (definition of PATCH) - HTTP Status codes: - https://lsantos.dev/status-codes-7231 - https://lsantos.dev/status-codes-9110 - https://lsantos.dev/status-codes-list - https://lsantos.dev/lsantos-status-codes (my article about it) - https://lsantos.dev/expresso-router - https://lsantos.dev/mvc-example
66. tack_ lsantos.dev