Twitter | Search | |
Marc-André Giroux
🔥 API Design Pitfall 🔥 1/ In API design in general, there is tension between building something generic or specific. For most web APIs, I've seen something more specific leading to better design. Thinking about client *intent* is a good way to see it.
Reply Retweet Like More
Marc-André Giroux 2 Jul 19
Replying to @__xuorig__
2/ Here's a simple example of an API exposing a generic way of querying an API for a user's archived posts.
Reply Retweet Like
Marc-André Giroux 2 Jul 19
Replying to @__xuorig__
3/ And here's the intent-based / use case focused version.
Reply Retweet Like
Marc-André Giroux 2 Jul 19
Replying to @__xuorig__
4/ The generic one may seem more powerful and evolvable at first sight, but it has its gotchas: 1. Much more knobs to turn and tune for the client 🎛 2. Much more complex on the server side 🤬(performance more generic filters can especially be hard to achieve)
Reply Retweet Like
Marc-André Giroux 2 Jul 19
Replying to @__xuorig__
5/ 3. The specialized version is much more cacheable. ⚡️ 4. Consistency! our API is very clear on what experience clients get, leading to a more evolvable API down the line. ☺️
Reply Retweet Like
Marc-André Giroux 2 Jul 19
Replying to @__xuorig__
6/ Fields that are too generic are sometimes there because they're used as a way to DRY up the server side implementation. Don't try too much to DRY your interface (GraphQL Schema), DRY your implementation (resolvers) if needed. 💧 When in doubt, keep it simple 🧘‍♀️
Reply Retweet Like
Marc-André Giroux 2 Jul 19
Replying to @__xuorig__
7/ There are some use cases where a super generic API is what we want, but I've found these cases to be quite rare. Your API probably won't fit at either extreme, but a balance between the two. This will all be covered in here soon: 📒
Reply Retweet Like
Nick Schrock 2 Jul 19
Replying to @__xuorig__
💯💯💯 so many people are tempted and do end up putting in some sort of generic dsl for filtering in strings. Not the way it was intended to be used at all. Highly tailored API eases the burden of server implementations so much
Reply Retweet Like
Andy Ingram 🌀 3 Jul 19
Replying to @schrockn @__xuorig__
I tend to advocate for it when you genuinely need, like an e-commerce search engine. But until you get to that point, start as specific as possible and only worry about generic abstractions when you have a clear use case.
Reply Retweet Like
Hin 2 Jul 19
Replying to @__xuorig__
Wow I learn so much about APIs from you. Keep it up man
Reply Retweet Like
JP 2 Jul 19
Replying to @__xuorig__
🙌🙌
Reply Retweet Like