Parameter naming differences are confusing

[jeff-h]

It seems this PHP library uses slightly different parameter names than the API documentation describes. Root-level names are usually camelCased (but not always, see template below), where in the API they are under_scored, but nested parameters are left the same as the API (I think).

eg

php	API docs
substitutionData	substitution_data
template	template_id

This introduces confusion — could they be made the consistent with the API?

[jeff-h]

Looking deeper in the code, this looks like a deliberate decision, so I'm wondering whether you could add a paragraph to the README explaining why, and documenting the mapping?

I just found the mapping enumerated in /SparkPost/Transmission::$parameterMappings. It would have certainly helped if I'd seen that earlier.

  protected static $parameterMappings = [
    'attachments'=>'content.attachments',
    'campaign'=>'campaign_id',
    'customHeaders'=>'content.headers',
    'description'=>'description',
    'from'=>'content.from',
    'html'=>'content.html',
    'inlineCss'=>'options.inline_css',
    'inlineImages'=>'content.inline_images',
    'metadata'=>'metadata',
    'recipientList'=>'recipients.list_id',
    'recipients'=>'recipients',
    'replyTo'=>'content.reply_to',
    'returnPath'=>'return_path',
    'rfc822'=>'content.email_rfc822',
    'sandbox'=>'options.sandbox',
    'startTime'=>'options.start_time',
    'subject'=>'content.subject',
    'substitutionData'=>'substitution_data',
    'template'=>'content.template_id',
    'text'=>'content.text',
    'trackClicks'=>'options.click_tracking',
    'trackOpens'=>'options.open_tracking',
    'transactional'=>'options.transactional',
    'useDraftTemplate'=>'use_draft_template'
  ];

[richleland]

Yeah we haven't kept the mapping up to date in the documentation @jeff-h. Worth noting is that we just decided to use camel case, no standards-based reason, just a decision from the early days of the lib. But more importantly, the libraries are typically not a 1:1 mapping. Take recipientList and rfc822 above for example - calling those recipientsRecipientListId and contentEmailRfc822 would've felt off in my opinion.

I think having the libraries abstract away some things in the API is helpful. I've also felt that having a 1:1 mapping with docs always defeated the purpose of a client library, but again that's just my opinion. Having said that, if we're going to abstract things, we need to document them properly and make it really easy to understand/consume - so thanks for the awesome feedback - and open to any further suggestions you have.

[jeff-h]

Thanks for your comments and explanations.

With the benefit of some thinking time, I think a little extra documentation would have saved my headaches on this :) Even just a pointer to the right place in the code (e.g. what I posted above) would do the trick.

[richleland]

Handled in the 2.x branch via #121 and #122.

[jeff-h]

Nice! :)