Re:How to (and how not to) design REST APIs
by aleksiy123 on Wednesday November 01, 2023 @05:37PM
(#38105698)
Second this. Reading this while working at google made me better design. Some that stand out to me are.
Resource Oriented Design: https://google.aip.dev/121
Declarative Friendly APIs: https://google.aip.dev/128
Declarative friendly makes writing scripts, pipelines so much better because of idempotency. It also pairs very naturally with resource Oriented design.
Long Running Operations: https://google.aip.dev/151
LROs are applicable to any request that runs longer than a second or a couple of seconds. Having a unified interface can be very powerful for implementing offline task workers and pipelines.
Filtering: https://google.aip.dev/160
This one is probably controversial as it's makes implementing basic filtering quite a bit harder. I haven't quite seen the issues it's supposed to solve play out in practice but it's interesting nonetheless.
- Optional but supported user defined identifiers, it's so frustrating to work with API that passes you back an identifier.
- String identifier (names) for resources, with some kind of type namespacing, i.e. the prefix in the author's document - Consistent set of fields (create_time, update_time, annotations, ...)
- Avoid dynamic map (this is a JSON self-inflicted wound)