What is the deal with ad hoc actions

[eileenmcnaughton]

How do we deal with ad hoc actions in api v4?

We currently have a bunch of really useful ad hoc in api v3 - I want to use api v4 but I need to call

Contact.merge
Job.process_batch_merge

I think it would be possible to have api v3 remain the holder of ad hoc actions - but then we would miss the opportunity to eventually deprecate them. If we are to bring them to api v4 we'd need unit tests for them - perhaps we could manage in the test suite that we run tests under both apiv3 & api v4 to save lots of re-writing. But we have to decide about making actions available in apiv4 first.

I think this is what @mattwire was indicating was a blocker to him adopting apiv4

[colemanw]

To answer your question in a nutshell, ad-hoc entities and ad-hoc actions are very well supported in api4.

Documentation on the subject is not as complete as I would like, but the readme does cover the basics:

Architecture
A set of DAO action classes (e.g. DAOGetAction, DAODeleteAction) exists to support DAO-based entities. DAOGetAction uses Api4SelectQuery to query the database.
A set of Basic action classes (e.g. BasicGetAction, BasicBatchAction) exists to support many other use-cases, e.g. file-based entities.

Adding an action to an existing entity:
Create a class which extends a generic action class (see below). Give it the same namespace and file location as other actions for that entity. It will be picked up automatically by api4's getActions file scanner.

Adding a new api entity:
If your entity has a database table and DAO, simply add a class to the Civi/Api4 directory of your extension. Give the file and class the same name as your entity, and extend the DAOEntity class.

For specialty apis, try the BasicGet, BasicCreate, BasicUpdate, BasicBatch and BasicReplace actions as in this example.

[eileenmcnaughton]

@colemanw OK - but what about dealing with core api in apiv3 - how would we port the ones of those that we want - AND deal with the test issue - ie. the api above exist in apiv3 and are heavily tested...

[colemanw]

Well if the ad-hoc action is just a wrapper around a bao function then there's not much to porting it.

[eileenmcnaughton]

@colemanw right but the issue is the tests - we have say 100 ad hoc api functions that need to be supported in apiv4 before people will make the switch and about 60 that would not be ported. But there is no point in porting them if we don't figure out how to port the tests

also @totten

[colemanw]

Agree the api3 tests bring a huge amount of value to CiviCRM. But stepping back a bit...

1. Api3 isn't going away anytime soon. So porting the tests doesn't have to happen overnight.
2. Porting all the api3 tests for an entity/action shouldn't be a prerequisite for adding that entity/action to api4.
3. A wrapper for running api3 tests in v4 would be clever and valuable. Could be added as a trait on a class-by-class basis. Might work better for some entities than others.
4. New tests in api4 are also useful, as are reworked/ported api3 tests.