Dear Eloqua REST API Team,
I'd like to lobby for a moment here. I have a complaint and a suggestion for resolution regarding your REST API.
Using the REST API, there are several fields for the Contact record which are... odd. Specifically, the fields can be discovered using the field discovery call (GET /API/REST/1.0/assets/contact/fields?depth=complete), but when the data is requested using the data call (GET /API/REST/1.0/data/contacts?depth=complete&page=1) some of the discovered fields are not populated and the data for those fields are provided in a different, non-discoverable structure.
For example, let's say we want to extract email and the email display name. The field id for email address is 100001. For email display name, it's 100005.
The response for a single record might look like this:
{"type":"Contact","id":"1","emailAddress":"tzicornell@ohmy.test.com","fieldValues":[{"type":"FieldValue","id":"100005","value":"Topher Z"}]}
The email address comes in a named property field and NOT in a field referenced by 100001, while the email display name comes identified by the field id in a list of generic field values. That's odd, and requires special coding to handle data coming in different ways. But that's not such a Big Issue.
Further, the field name given as the property name is different than the field name given in the field discovery. That's also odd, and also requires special coding to handle. But as long as the field name follows a derivable pattern from the field discovery (remove the preceding "C_" and lowercase the first char), that's also not such a Big Issue.
The Big Issue comes when the property name is completely different than the field name given in the field discovery. For example, C_BusPhone is what is discovered, but businessPhone is the property in which the data is provided. There's no way to handle that automatically.
So, now, not only does any automation code have to handle pulling from both named fields and a referenced field-value list, not only does it have to look for field names adjusted by arbitrary rules, but it also has to keep a hard-coded mapping of this field to that field name. This makes coding for the API complicated, error-prone and brittle. Additionally it completely breaks the whole point of field discovery.
But wait, there's more. To aggravate this problem, over the past month, the discovered field names and the property names (not discoverable) have been diverging. So suddenly, a solution which works perfectly well suddenly stops providing the business phone number field, or the company name, or the postal code.
My suggestion for resolving this is to provide all the data for fields that are discoverable by the field discovery call through the fieldValues list, and deprecate all the properties that are providing said field data (to be removed at a later date).
So, the response above for vNow+1 could look like:
{"type":"Contact","id":"1","emailAddress":"tzicornell@ohmy.test.com","fieldValues":[{"type":"FieldValue","id":"100001","value":"tzicornell@ohmy.test.com"},{"type":"FieldValue","id":"100005","value":"Topher Z"}]}
And the response for vNow+2 or vNow+3 could be:
{"type":"Contact","id":"1","fieldValues":[{"type":"FieldValue","id":"100001","value":"tzicornell@ohmy.test.com"},{"type":"FieldValue","id":"100005","value":"Topher Z"}]}
Note that this suggested change should ONLY affect discoverable fields, not actual properties, like type, id, depth, etc.
This solution will disassociate the field name from the value, provide a much cleaner experience for all your API coders and remove the brittleness you're currently forcing into any solution that integrates with your REST API.
Regards,
. Topher