So, how should our version 3.0 api look?

[Eileen]

So, I've been working on an api for pledge which is here:

https://svn.fuzion.co.nz/repos/fuzion-code/trunk/civicrm/core/CRM/api/v2/Pledge.php

I am trying to do it according to the standards we are trying to implement but I'm wondering about the _civicrm_contribute_format_params function that is found in the contribute & membership APIs but not much else. I feel this is either useful & should go in the other APIs (as they are updated) or not useful & should come out.

The function does some format checking & returns errors. It restricts you to using the 'variant' of the field name returned by the $fields function e.g.in the context of pledge this is  'pledge_amount' instead of  'amount'.  This is less flexible but it does mean that the values you can pass in are the same as those you get back. Ie. the GET function brings back 'pledge_create_date' so it is consistent with that.  But on the other hand it seems kind of high maintenance.

So, we can go the way of the Event API - which accepts & returns both event_description and description (it took me a while to make sense of the 'difference' between these two fields returned to me and I got in a bit of a mess with that because I was basing my 'Add' event fields on my 'get' fields & did a bit of testing to find out where the 'two' fields went - which kind of comes back to why I am so keen to pin down how the API *should* behave). Or we can pin the API down to only accepting a single variant for each of the fields which reflects the value returned by the fields function. Not sure which is better.

I did try playing around with the idea of an 'interogate' function - the function I have in there returns this at the moment - in theory these are the fields you can pass in. The values are not interpreted at the moment but they are data type - e.g. 1 = integer

<?xml version="1.0"?>
<ResultSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Result>
    <pledge_id>1</pledge_id>
    <pledge_contact_id>1</pledge_contact_id>
    <contribution_type_id>1</contribution_type_id>
    <contribution_page_id>1</contribution_page_id>
    <pledge_amount>1024</pledge_amount>
    <pledge_original_installment_amount>1024</pledge_original_installment_amount>
    <currency>2</currency>
    <frequency_unit>2</frequency_unit>
    <frequency_interval>1</frequency_interval>
    <frequency_day>1</frequency_day>
    <installments>1</installments>
    <start_date>12</start_date>
    <pledge_create_date>12</pledge_create_date>
    <acknowledge_date>12</acknowledge_date>
    <modified_date>12</modified_date>
    <cancel_date>12</cancel_date>
    <end_date>12</end_date>
    <honor_contact_id>1</honor_contact_id>
    <honor_type_id>1</honor_type_id>
    <max_reminders>1</max_reminders>
    <initial_reminder_day>1</initial_reminder_day>
    <additional_reminder_day>1</additional_reminder_day>
    <pledge_status_id>1</pledge_status_id>
    <pledge_is_test>16</pledge_is_test>
    <installment_amount></installment_amount>
    <custom_48>String : Dept</custom_48>
    <custom_51>String : Worker Select</custom_51>
    <custom_55>String : Commission</custom_55>
    <custom_56>String : First Time Credit Card</custom_56>
    <custom_57>Int : Donation Increased by</custom_57>
    <custom_60>String : Promo (Marvin)</custom_60>
    <custom_61>String : Restrct</custom_61>
    <custom_63>String : t</custom_63>
    <is_error>0</is_error>
</Result>
</ResultSet>


does allow us to try to implement an 'interrogate' or discover function

[Eileen]

Hi,

I've updated the pledge API as I see fit & written a test case but it needs some QA


https://svn.fuzion.co.nz/repos/fuzion-code/trunk/civicrm/core/CRM/api/v2/Pledge.php

I decided to handle as many of the options I thought people could reasonably expect it to as possible (both field name & db unique name) & flushed out quite a gotchas (bashed my head against more the point). Not sure this will be seen as the right approach by everyone as it seems a little over-complicated & inelegant but a big time saver from the point of view of someone using it. Also, I wrote the code in a way that allowed me to write lots of comments because it would be easy otherwise to think that using 'pledge_id' rather than 'id' would make more sense so I wanted to document which error I hit with that & also with 'pledge_create_date'

[Eileen]

Linking this with a JIRA

http://issues.civicrm.org/jira/browse/CRM-6873