Multiple problems using API create to update entities

API create has been recommended by API developers to be used for updating entities instead of using API update. To discourage use of API update, the update action is slated to be removed from the API explorer for v4.3 (CRM-12140). However, there are still multiple problems that need to be fixed before API create can replace API update.

When using the API to update an entity, you should only have to supply values for those fields whose values are changing, and you'd expect the entity's other fields to keep their existing values. However, for several entity types, if you omit certain fields from the API create call, it will cause an error or alter the values of fields you did not specify.

Several recent bug fixes have addressed problems of this nature:

• CRM-10921: OptionValue create was altering the values of various fields if they weren't supplied.
• CRM-11228: Contact create was resetting contact subtypes to empty if contact_sub_type was not supplied.
• CRM-11789: Relationship create was resetting relationships to inactive if is_active was not supplied.

However, there remain several other problems of this nature. In version 4.3 beta 3, I found the following problems with using API create to update various types of entity:

• OptionGroup: Gives an error if name is not supplied. Most fields are altered if they are not supplied.
• CustomGroup: Most fields are altered if they are not supplied.
• CustomField: Most fields are altered if they are not supplied.
• Group: Group type is reset to empty if it's not supplied.
• Tag: Gives an error if name is not supplied.
• Note: Gives an error if name is not supplied. Resets privacy to zero if it's not supplied.

This is not a comprehensive list. If API update is to be replaced by API create then API create needs to be tested for all entity types to see if there are any more of these problems. I propose as a minimum test: For each API, populate all fields of an entity with non-default values, then call API create specifying only the entity's id, then check to make sure that no fields have been altered.

Until these problems have been fixed, I think it would be premature to retire the update action or to encourage people to use API create as a substitute for API update.