facilitate data-entry-entities via api

We need to be able to do what certain forms do by using the api.

In this case my focus is on submitting profiles but we should also consider submitting event forms & contribution pages in this mix because there is a cross-over requirement.

Profile, contribution_page, event & to a lesser extent batch describe a configurable data entry unit. We want the ability to leverage the configuration built into these units outside the form layer. The data entry unit divides somewhat into 'field selections & defaults' & form actions - add to group, send emails etc. In some cases an api would want to access only the fields selections & defaults in in others the whole schebang.

While we have had a lot of demand for this wrt contribution pages, & probably overall they are a larger painpoint, my current focus is on profiles - I raise the other forms as including them will influence the design choice.

Desired flow
1) retrieve sufficient data about a form-entity to generate a data input form or data entry grid for it (fields, types, specific validations, defaults)
2) enter data for one or more entries
2) validate data for one or more entries
3) submit data for one or more entries

I expect the flow to be managed by either the civi batch functionality or similar built outside of core. So, in this case the discussion is on the retrieve validate & submit on the data-unit-entities. As Tim has pointed out we can handle the one-or-more entities part of this question by using chaining of a null entity (I need to confirm the syntax on that) & if rollback is not desired then calling code can do them one@ a time.- so we don't need to solve the plural aspect of this. Note that this flow is also the same as is implemented by the various imports - although they don't currently use profiles it would make sense for them to eventually use a reserved profile.

Currently:

1) api for contribution_page, event, batch do not have any data entry functions - only entity functions
2) api profile.get retrieves one or more profiles (including pseudoprofile billing) for a particular contact id - e.g. CRM.api(''profile', 'get', {'contact_id' : 4, 'profile_id' :

) will retrieve those profiles prefilled for that contact.
3) api.profile.getfields returns non-useful information
4) api.profile.set = profile submit - with various limitations
5) api.profile.apply = internal function exposed as if it were an api function

So, I guess this brings us to options for how the profile api should look

1) I think that 'set' is not a good verb here & we should determine what the right one is & treat set as legacy.

2) Do we want one api action e.g. submit for when we want the whole schebang (including add to group etc) & one (e.g create) for when we are just submitting the fields of a profile & don't want any of the settings to be implemented (notifiy, add to group).

3) totten suggested a form api :

civicrm_api3('Form', 'submit', array('name' => 'ContributionPage', 'id' => 4, 'values' => array(…))

This seems kinda nice. If my breakdown above does make sense (splitting the form actions from the form data entry) then it would make sense to have this function as well as a ?submit? function on the contribution_page, event, profile apis?

4) we need a getfields-type-action that takes 'profile_id' , 'contribution_page.id' etc as an action & returns the appropriate fields

So, the requirement here is to determine appropriate actions to work towards implementing with regards to profile in the first instance

1) validate - can I propose validate as a verb for this
2) do we call the submit / create action 'submit' as that works best with contribution_page etc?
3) how do we differentiate which actions we want undertaken besides creating the entities (add to group, send receipt etc)
4) getfields - do we just enhance existing profile, contribution_page, event getfields to take 'id' as a param & alter the response based on that if the 'action' = submit
5) or - so we add a form api that does the submit on these pages (#3 still applies). Form api could have a getfields that takes 'formname' & 'id' & works off that. For validate & submit it could take those + a 'values' array. Which would still leave how we deal with whether or not to do the actions