The Hitchhiker's Guide for an Amazing API with TypeScript

Slide 1

Slide 1 text

TS Hitchhiker's Guide For an amazing API design

Slide 2

Slide 2 text

$ whoami_ {twitter, youtube, linkedin…}.lsantos.dev founding engineer_ hello@lsantos.dev

Slide 3

Slide 3 text

whats and hows ﬁrst and foremost, what's this all about - General best practices - Using TypeScript in APIs - Going Beyond TypeScript

Slide 4

Slide 4 text

DISCLAIMER

Slide 5

Slide 5 text

BUT

Slide 6

Slide 6 text

there are three_ rules of a sensible API design

Slide 7

Slide 7 text

Be consistent

Slide 8

Slide 8 text

response schemas_

Slide 9

Slide 9 text

response schemas_ response schemas_

Slide 10

Slide 10 text

response schemas ❌ response schemas_

Slide 11

Slide 11 text

response schemas ✅ ❌ response schemas_

Slide 12

Slide 12 text

response schemas response schemas_

Slide 13

Slide 13 text

response schemas cannot read property length of undeﬁned response schemas_

Slide 14

Slide 14 text

response schemas response schemas_

Slide 15

Slide 15 text

bottom line

Slide 16

Slide 16 text

dynamic keys_

Slide 17

Slide 17 text

dynamic keys dynamic keys_

Slide 18

Slide 18 text

dynamic keys dynamic keys_

Slide 19

Slide 19 text

dynamic keys dynamic keys_

Slide 20

Slide 20 text

dynamic keys dynamic keys_

Slide 21

Slide 21 text

dynamic keys dynamic keys_

Slide 22

Slide 22 text

dynamic keys dynamic keys_

Slide 23

Slide 23 text

bottom line

Slide 24

Slide 24 text

output consistency outputs should be predictable - Same structure if possible - Same casing - Same building logic

Slide 25

Slide 25 text

class-based responses

Slide 26

Slide 26 text

ﬁnal thoughts on consistency - Use sensible endpoint names - Use sensible HTTP verbs

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

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

Slide 29

Slide 29 text

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 oﬀers

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

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)

Slide 32

Slide 32 text

Be descriptive

Slide 33

Slide 33 text

correct HTTP status codes yes, there's life beyond 200, 400 and 500

Slide 34

Slide 34 text

status codes cheat sheet: the good - Deleted something ➡ 204 - Created something ➡ 201 - Will do something ➡ 202 - All others ➡ probably 200

Slide 35

Slide 35 text

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 stuﬀ on body ➡ 413 - Didn't implement that method ➡ 405 - and so on… Avoid 400

Slide 36

Slide 36 text

the http status code cheat sheet: the ugly - Server messed up ➡ 500 - Future implementation ➡ 501 - Routing issues ➡ 502, 503, 504 (depending on the case)

Slide 37

Slide 37 text

error standardization

Slide 38

Slide 38 text

error standardization

Slide 39

Slide 39 text

error standardization

Slide 40

Slide 40 text

OpenAPI the best thing to have, terrible to maintain

Slide 41

Slide 41 text

spec as code: from spec to code 📝 ➡ 👾

Slide 42

Slide 42 text

spec as code: from code to spec 📝 ⬅ 👾

Slide 43

Slide 43 text

you don't have to do it from scratch

Slide 44

Slide 44 text

you don't have to do it from scratch

Slide 45

Slide 45 text

you don't have to do it from scratch

Slide 46

Slide 46 text

Be deterministic

Slide 47

Slide 47 text

schema driven development kneel before Zod - deﬁne once, derive everywhere - single source of truth - built-in error handling

Slide 48

Slide 48 text

No content

Slide 49

Slide 49 text

schema driven development

Slide 50

Slide 50 text

schema driven development

Slide 51

Slide 51 text

schema driven development

Slide 52

Slide 52 text

global conﬁgs, local overrides schematize your envs - environment validation - conﬁguration always present - intellisense - better security

Slide 53

Slide 53 text

global conﬁgs

Slide 54

Slide 54 text

global conﬁgs Use the Node native --env-file ﬂag

Slide 55

Slide 55 text

ﬁnal quick tips

Slide 56

Slide 56 text

let it break, handle errors globally

Slide 57

Slide 57 text

let it break, handle errors globally

Slide 58

Slide 58 text

separation of concerns

Slide 59

Slide 59 text

separation of concerns 󰠤 User

Slide 60

Slide 60 text

separation of concerns 🎨 Presentation layer > validation > calls services > formats responses 󰠤 User

Slide 61

Slide 61 text

Slide 62

Slide 62 text

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

Slide 63

Slide 63 text

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 deﬁnitions 💽 Data Layer > interacts with the database > external apis > receives domain objects > returns domain objects > never errors > can only be called by services

Slide 64

Slide 64 text

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 deﬁnitions 💽 Data Layer > interacts with the database > external apis > receives domain objects > returns domain objects > never errors > can only be called by services

Slide 65

Slide 65 text

refs_ - https://lsantos.dev/rfc2616 (deﬁnition of HTTP methods) - https://lsantos.dev/patch-method (deﬁnition 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

Slide 66

Slide 66 text

tack_ lsantos.dev