CiviCRM Community Forums (archive)

In APIv3, the norm is to do updates based on matching IDs; if you want to match/update based on a different field, then it normally requires multiple calls -- e.g. do a "get" followed by "create". There's some options which are useful for doing a get+create in a more concise fashion:

• API chaining -- Issue a 'get' call with a nested 'create'
• options.match -- http://wiki.civicrm.org/confluence/display/CRMDOC/API+changes#APIchanges-4.4.0:%27create%27and%27replace%27actionsaccept%27options.match%27or%27options.match-mandatory%27

The behavior you point out in the Dashboard API isn't normative; it's more adhoc. This is not entirely unusual -- it often happens with a story like this:

• Developer #1 creates a BAO function (e.g. CRM_Core_BAO_Dashboard::create or CRM_Core_BAO_Dashboard::addDashlet) for a specific use-case. The function has some special behavior which makes sense for that use-case.
• A few months later, developer #2 creates an API. The API builds on top of the existing BAO function, and developer #2 assumes that the BAO function works "normally" (or assumes that anything unusual is good or exists for a valid reason).
• The assumption may or may not be valid. If the assumption is wrong, then eventually someone realizes that the API is weird.

The most authoritative way to find out what's going on in this situation is to read the BAO code.

• https://github.com/civicrm/civicrm-core/blob/4.5/CRM/Core/BAO/Dashboard.php#L50
• https://github.com/civicrm/civicrm-core/blob/4.5/CRM/Core/BAO/Dashboard.php#L411