Upgrade to Pro — share decks privately, control downloads, hide ads and more …

The Hitchhiker's Guide for an Amazing API with ...

The Hitchhiker's Guide for an Amazing API with TypeScript

Lucas Santos

May 06, 2024
Tweet

More Decks by Lucas Santos

Other Decks in Programming

Transcript

  1. whats and hows first and foremost, what's this all about

    - General best practices - Using TypeScript in APIs - Going Beyond TypeScript
  2. BUT

  3. output consistency outputs should be predictable - Same structure if

    possible - Same casing - Same building logic
  4. once upon a time in a company I worked for

    https://api.mycompanydomain.com/v1/getOffers
  5. once upon a time in a company I worked for

    POST https://api.mycompanydomain.com/v1/getOffers
  6. 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
  7. 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
  8. 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)
  9. status codes cheat sheet: the good - Deleted something ➡

    204 - Created something ➡ 201 - Will do something ➡ 202 - All others ➡ probably 200
  10. 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
  11. the http status code cheat sheet: the ugly - Server

    messed up ➡ 500 - Future implementation ➡ 501 - Routing issues ➡ 502, 503, 504 (depending on the case)
  12. schema driven development kneel before Zod - define once, derive

    everywhere - single source of truth - built-in error handling
  13. global configs, local overrides schematize your envs - environment validation

    - configuration always present - intellisense - better security
  14. separation of concerns 🎨 Presentation layer > validation > calls

    services > formats responses 󰠤 User ⚙ Service Layer > interfaces with other services > interfaces with one repository > external business logic
  15. 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
  16. 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
  17. 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
  18. 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