Twitter | Search | |
Marc
πŸ”₯ 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 Jul 2
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 Jul 2
Replying to @__xuorig__
3/ And here's the intent-based / use case focused version.
Reply Retweet Like
Marc Jul 2
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 Jul 2
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 Jul 2
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 Jul 2
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
Scott Walkinshaw Jul 2
Replying to @__xuorig__
Sometimes it's hard to design properly from the start so there's two ways to evolve these decisions as well: * start generic then promote popular ones to be their own fields * start specific then add the generic feature if people start to need more powerful filtering
Reply Retweet Like
Marc Jul 2
Replying to @swalkinshaw
Right on, exactly. If people need powerful filtering it now becomes an actual use case! Great points
Reply Retweet Like
Nick Schrock Jul 2
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
Lewis Chung Jul 2
Replying to @__xuorig__
Looks like a great example of where YAGNI helps. Going with the `where:` filter approach assumes there will be many more filters (or at least makes it less clear whether or not there are more filters).
Reply Retweet Like
Hin Jul 2
Replying to @__xuorig__
Wow I learn so much about APIs from you. Keep it up man
Reply Retweet Like
Superjon Patell Jul 2
Replying to @__xuorig__
πŸ™ŒπŸ™Œ
Reply Retweet Like
Superjon Patell Jul 2
Replying to @__xuorig__
Love this. Was just thinking about this today as I’ve been playing with a few different impl. lately and I find those that try to wrap the API around a data model/dB paradigm rather than the client ideal/intent, seduce / maybe even req. one to abstract lower in the stack.
Reply Retweet Like
Andy Ingram πŸŒ€ Jul 3
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
Andy Ingram πŸŒ€ Jul 3
Replying to @schrockn @__xuorig__
Though I think we’ve all been saying this exact thing for the last 4 years :p
Reply Retweet Like
Marc Jul 3
Replying to @andrewingram @schrockn
Yep and then if you need an e-commerce search engine, it's now a clear use case :)
Reply Retweet Like
Sibelius Seraphini Jul 4
Replying to @__xuorig__
For almost all connections with have a single filter input type, so we can reuse the same connection filters in a lot of places using the same resolvers
Reply Retweet Like
Sibelius Seraphini Jul 4
Replying to @__xuorig__
Choosing to have specific fields could help but it will cause other problems
Reply Retweet Like