Yes, you’re talking about the proliferation of declarative APIs over explicit, imperative ones.
My pet theory is that because we typically understand our needs before we understand the code paths required to fulfill them, our V1 APIs are usually a declarative “this is what should be” interface. Then we spend days or months making it happen and by the time we understand the required code paths, we’ve totally baked our expectations about the “make it so” API into our architecture.
Getting to a good, explicit, imperative API requires a whole nother step, and often a major refactor. You have to step back and ask “what is really happening now and can I conduct it more directly?”
... but by that time your code works and it hardly seems worth the effort.
But it is worth the effort. The declarative API will just get uglier as you add to it, and provide no real guidance about where future additions should go. Just throw another key in the config. Add another conditional. An imperative one will constrain your future choices about how additions can work, and therefore helps you clarify your domain model as you add to it.
I think your theory and seeming aversion to declarative interfaces is a bit too general.
Many declarative interfaces are the culmination of decades of work on re-inventing the wheel at the imperative level. The relational model and SQL databases are a great example of this - “we’ve solved these problems below this line mostly, please move on and focus up the stack closer to the customer/user”. It became a multi billion dollar industry as it nailed the 80/20 rule for data management.
And for a large class of problems this remains solid, despite a perpetual subset of engineers that think they can do better than the declarative interface and engine and build an alternative. Sometimes it makes sense to be adventurous and drop back to the imperative level - SQL databases fell over in recent years was the scalability of the underlying engine for the largest uses. But a Postgres or MySQL endures as a great declarative abstraction over a very complicated set of issues.
No, I agree with you. There are some great declarative interfaces and there are many problems best solved by one.
SQL is a great example. But it’s also an example of how difficult it is to make a great declarative API. Look how much effort went into designing and then refining and then adapting SQL to changing needs. It’s been an enormous effort across a huge community.
Same with CSS. Those aren’t things some developer just wrote and they got refined in an application over time. There are entire conferences about the regular redefinition of those interfaces.
My point is that concept doesn’t scale to some large number of abstractions. SQL and CSS are big manifolds that operate on the boundary of your application, and often separate you from an entire other group of developers working to maintain the other side of that contract.
If you try to apply that same setup to every problem, with thousands of declarative manifolds all intersecting within your application, you get chaos. Which is what many modern frameworks try to do. Declarative APIs only work when they are rare and standard and everyone knows them.
My pet theory is that because we typically understand our needs before we understand the code paths required to fulfill them, our V1 APIs are usually a declarative “this is what should be” interface. Then we spend days or months making it happen and by the time we understand the required code paths, we’ve totally baked our expectations about the “make it so” API into our architecture.
Getting to a good, explicit, imperative API requires a whole nother step, and often a major refactor. You have to step back and ask “what is really happening now and can I conduct it more directly?”
... but by that time your code works and it hardly seems worth the effort.
But it is worth the effort. The declarative API will just get uglier as you add to it, and provide no real guidance about where future additions should go. Just throw another key in the config. Add another conditional. An imperative one will constrain your future choices about how additions can work, and therefore helps you clarify your domain model as you add to it.