Ask HN: Whats your favorite book on API design?

2 points by escot 2 years ago | 2 comments

illuminant 2 years ago |

Will save you some trouble reading a book. Wisdoms I've learned over the years...

- single entry point (/api/) which delegates dynamically to named resources in a components (or "plugin") folder. (So /api/user/... Is delegated to (app/plugins/user.ext) which may subroute.

- Do not follow full CRUD. Instead only support GET and POST. Use POST to upsert. If no GUID (0), it's new. Delete is a flag (never actually remove records, instead set a delete flag and use that in queries.) (Note: not universally popular yet practical)

- Use ULIDs or UUIDv7+ (serialized, timecoded, good entropy.) If you want to be hard core (best index performance), save in db as binary and convert to conventional format for front end usage.

- do not return a raw data set result, instead return an envelope containing the data set { status, message, data }. Set proper HTTP response headers.

- generate a single use session token on authorization (set in the HTTP request header), use that to track sessions.

- dont use redundant names (/api/user/user_profile) just use /api/user/profile. Seems obvious and yet ...

Hope you find this helpful! Let me know if I haven't addressed something (or to argue about that CRUD COMMENT ;)

escot 2 years ago | |

Thanks. Im interested in a book that explored more advanced design patterns. Like, supporting copying a resource. Or supporting —dry-run type functionality for requests that have side effects.