Fred Friis

04/27/2023, 1:21 PM
not specifically arrow related but asking in here anyway because I value folks opinion here more than most: how do you avoid bikeshedding when designing rest apis? any favorite standards or frameworks? (eg json api, open api etc) every place I've ever worked there's been quite a bit of varying opinions on how to implement even basic crud operations (including even what status codes to return etc haha) to be clear, I think the term bikeshedding is sometimes used to unfairly dismiss what is actually valuable discussion about the semantics of an api - many apis I've worked on have come out much better because of "bikeshedding" (and didn't really follow any of the standards mentioned above) that said, there's definitely a point where it becomes unproductive, and if you're in an org where opinions differ too much, simply adopting a standard (even if everyone has their own reservations about it) and sticking to it religiously might be better... anyway yeah would love to hear your takes on this!

Youssef Shoaib [MOD]

04/27/2023, 1:25 PM
Json by default, ProtoBuf for performance. Return a success of empty list for searches that have no results, and return 404 for any other
not found
states. Also, as long as you design your clients and servers well, the rest API itself will be an implementation detail that can easily change and evolve, so I'd say focus on the domain of your data and what fits best for it, and the rest apis can be changed when need be.

Fred Friis

04/27/2023, 1:51 PM
json by default
likewise 🙂 but it doesn't say much about the style of response eg do you return the object directly or surronded by meta json (like json api standard does) and re clients, how much do you optimize for them vs more academic correctness (as for me, sometimes, I lean towards reducing the number of ways the api responds in different cases so clients have to worry less about handling 200 object, 200 but no object, 201, 204, 404 nothing found etc etc (even if that would technically be more correct or whatever) obviously you can't do that for everything, eg GET user/xyz if no such user exists, you can't return 2xx and an empty user lol but yeah basically sometimes favor reducing the number of different responses vs technical correctness as long as it's not super unidiomatic