Design principles: "Clean" Avoid exposing implementation details about org.civicrm.api4 HOT 4 CLOSED

I think it could be good to open a ticket for:

"Specify cache signature" - would be good to have some focussed conversations on this -

Isn't the issue with "exposing implementation details" more that we want a stable API - ie it's not that keeping implentation a secret is a problem - it is more that we need to ensure we don't have to change API signature in the future?

If we have a good pattern that will be friendly for coders that we don't need to change in the future, that is the main thing right? I'm concerned about "dont reveal the implementation" as a goal in itself as often having a thin layer around the "correct" implementation is going to look just like that

from org.civicrm.api4.

^^^ @xurizaemon does that make any sense at all, or have I misunderstood?

from org.civicrm.api4.

Yeah I think you've understood fairly correctly. Ideally what I'm asking is let's have as a goal the API signatures being as clean as possible, without needing people to know about internals. For me this means things like:

• Entities and column names preferring "natural" terminology over than "whatever's in the DB schema"
• Offering paging not requiring exposing a civicrm_prevnext_cache entity (IDK, maybe I misunderstood this comment from chat.civicrm.org)
• Encapsulating the query interface to permit filtering without risking security.

from org.civicrm.api4.

cool!

I think the first one could be it's own case?

yes lets agree forever never to expose any entity with cache in it!

re filtering - i think we have it nailed - but need to think about harder about #43

do we need to keep this issue open do you think?

from org.civicrm.api4.