CiviCRM Community Forums (archive)

In follow up to an earlier thread (http://forum.civicrm.org/index.php/topic,14955.0.html Xavier and I spoke last week to see where we thought the API standards were at. Some background: Some time ago Wes Morgan started a crusade to smarten up the API. He pitched idea, rallied troops & got the ball rolling. The standards document he created is here http://wiki.civicrm.org/confluence/display/CRM/API+Conventions. More recently Wes's evangelical zeal has morphed into the bleary eyes of a parent to a small bundle of tears & milk gluttony and his leadership in this area has been in short supply.

Anyway, the conversation that Xavier and I had is that the ideal is still to work towards have the standardised API verbs descibed in the standards

GET
CREATE
DELETE
UPDATE

This means that add functions and search functions that exist in current APIs should be deprecated over time. The correct response from any GET function is an array of the relevant entity that matches the criteria passed in. Normally the indexes of the array is the contact ID but we discussed that it would frequently be really useful to be able to pass in an additional parameter (e.g. 'sequential' = 1) that causes the resulting array to be indexed from zero.

We didn't discuss it over skype but the standards doc mentions the possibility of having version passed in as standard and I think this would be a good idea. The API has changed significantly before and perhaps could do again. Already the location API uses different behaviour dependent on the setting of the version parameter and some others act in ways quite disparate from each other and the standard. Initially, as with the location api, the default would be the old behaviour if no version is set but over time the version could become compulsory.

We also agreed that the desired path for the Contact_GET function (and any others affected) was that it would be changed to not use elevated privelleges (by-pass ACLS) and developers accessing the function via PHP would need to switch user before and after running it. Elevated priveledges would not longer be available via the REST method (which is appropriate as any user can use the API in this way). We didn't talk about the smarty template method & how you would be able to use elevated privelledges there is you wished (or if that was appropriate) but Xavier's opinion was fixing the security was high enough priority to do it & require developers to rework their use of the API if necessary. More people use ACLs than use ACLs plus API so more people benefit than have to re-work

We agreed some sort of discover or interogate function would be really useful but didn't come up with a clever way to implement.

So, really most of this is just re-stating the standards previously discussed. Although this is still 'scratch-your-itch' implementation getting / confirming clarity about how it should be implemented addresses one of the biggest barriers to submitting code fix-ups for CiviCRM. I would really like to come up with a clever way to make the API self-documenting through a discover function that draws off the DAO plus add-ons but the DAO doesn't quite match the appropriate API fields e.g. pledge_total_amount vs total_amount

NB - I have submitted a couple of minor API patches - adding soft_credit to contribution & preventing Core error on relationship API

Hi,

Also my point was that if your api needs to bypass the ACL, then grant the access right to see all contacts to the user you have for your api (that should be a different account than a real user anyway)

X+

In my experience when you want to fetch "more" is from the REST interface. In that case, you MUST specify the user, so you simply have to use one that has the right access rights.

But not that you mention it, we are using the api (smarty) to fetch a list of "public" contacts and display them. It wouldn't work anymore if we fix the security.

Somehow, it needs for the api on smarty or php to set the user, or bypass access rights I'm thinking.

(and if someone can run a php script in your server, that it can set a flag to bypass acls is not your main security issue)

X+

I'm very happy to see this moving forward again. I'm not working with the API anymore (my day job has changed), but improving it would be a huge help to CiviCRM developers and integrators everywhere. Godspeed!

Maybe you all have covered this already, but I wanted to be clear that having a CRUD foundation to the API is a starting point, but then certain non-orthogonal convenience methods should be added (or kept, if they're already there) to add to API usability.

For example, lots of information that is naturally associated with an individual contact like email address, mailing address, etc. is actually stored in separate associated objects in CiviCRM. So once the API provides a solid CRUD foundation, then a method should be added to allow contact creation with all this information provided in one shot. And then it should call the orthogonal methods behind the scenes (i.e. don't duplicate the code). There are probably several other non-orthogonal methods that should be added in addition to this. Anyway, that's my $0.02.

Now I need to go change a diaper...

Hi Wes, the functions I want to see deprecated are those that are variants on the CRUD functions (search, add). But I don't anticipate anything more agressive than marking them as deprecated.

Lobo, re the security thing - people currently using the get functions (primarily contact_get) and relying on them to return details for more than just those the logged in user can access will need to modify their code to either change users before calling the function (Php) or potentially resurect the profile api idea which will only retrieve details made available by configuring search profiles to expose them - which forces people to be cognissant of the information they are exposing.

There is no way to fix this hole without sites who are taking advantage of it having to re-work their code but the problem with a hole like this is it affects people who are using completely uncustomised CiviCRM and are utilising a core function (ACLS) which they could reasonably expect to be secure. Worst case scenario is that an organisation hires someone and using ACLS limits him to a small amount of contacts but using the REST URL and armed with only a floss manual is able to circumvernt the URL and do a search on name, address and interests (custom fields) of all children in the database within a preferred age range.

The problem with bugs like this is that the organisations impacted may never ever know about it but it could have consequences. The only organisation we deal with that uses ACLS is actually OK with them being only reasonably secure so I have no customer support for spending time on this issue but it bothers me when there are bugs that impact on people that they are completely oblivious to. I would have thought outfits like the Physicians mob would use ACLs and that they impact of them being easy to by-pass would be a major for them?

Would it be possible to implement a wrapper API that basically call other APIs with elevated permissions and make this API not available to REST?

Which then asks the question as to which functions should be REST callable. I have only used GET but I imagine that REST is the primary interface for inter-app integration so I would imagine the best approach would be to start from an 'all-in' approach & then remove any that can't be properly restricted by permissions

Don't think permissioning is an issue for REST, as you need to login with a user first. The server using rest simply have to give this user the proper rights (eg. to see all contacts) so it works with the permissions intended.

For the smarty or php api, you convinced me it needs to be able to run with a different priority than the person seeing the page.

What about introducing in all the apis a new parameter: skipPermission, that is true by default for smarty+php, and false and non modifiable for ajax & REST?

There is still an issue (new feature) that we should address: how to give access via ajax to contacts the visitor doesn't have the right to see? eg: I have a profile so the employees of my members can register, the employee should be an autocomplete with ONLY the org that belong to my group "member organisations". Provide a tool to create a simple module that can define the 2 ajaxs call you want and skipPermission ?

yes, the rest api will go thru a "wrapper" api which checks if the api is rest callable and if any specific parameters need to be set (i.e. say include permissioning in the search request)

which means, that we can add the "permissioning" part as a parameter to the api (default can be set to true) and if enabled, the search is returned using the  permissioning system