Sendgrid-nodejs: Strange breaking changes in 3.0

[silentroach]

What is wrong with <3.0 api? Why do you think simple request wrapper is better than code with objects and methods that can be autocompleted by IDE?

It is strange for me that now I need to read the documentation to find some method I need and required parameters. For me the main thing for API client library is to hide all the low level processes.

[thinkingserious]

Hello @silentroach,

Thanks for your feedback!

What you describe is part of the aim of the second iteration of the new library. The first iteration was to get basic support for all the new v3 Web API calls and the v3 /mail/send endpoint. The previous library only supported v2 /mail/send and the HTTP client was tightly coupled to that endpoint. In addition, we removed third party dependencies for greater compatibility.

The first step towards the autocompletion functionality is the introduction of helpers. We have created a helper for the v3 /mail/send endpoint here: https://github.com/sendgrid/sendgrid-nodejs/tree/master/lib/helpers/mail. It's important to note that we are not done, this is just the first in many improvement iterations. For example, we setup all those getters and setters so that we can add in validation at the library level, preferable automatically based on our swagger specification. We also plan to create additional helpers for common use cases, such as templates and managing sub-users, and we hope the Node.js community will contribute some as well.

We want you (and all of the Node.js community) to be a part of this iterative improvement process. Within the next few weeks we will be creating a Milestone here in GitHub to help plan what we need to do for this next iteration. We will be considering all feedback, so please continue to make your voice heard.

With Best Regards,

Elmer

[silentroach]

Thank you for your response. Even with a helper I don't want to know anything about api versions and request paths - it is a library responsibility.

[thinkingserious]

Thanks @silentroach,

Here is what we are thinking so far. Right now we just have helper functions to create the request body, the next step is additional functions that do exactly what you want, make the implementation opaque. Here is one concrete example:

Right now, this is the simplest way to send a basic email:

  var helper = require('sendgrid').mail
  from_email = new helper.Email("[email protected]")
  to_email = new helper.Email("[email protected]")
  subject = "Hello World from the SendGrid Node.js Library"
  content = new helper.Content("text/plain", "some text here")
  mail = new helper.Mail(from_email, subject, to_email, content)

  var sg = require('sendgrid').SendGrid(process.env.SENDGRID_API_KEY)
  var requestBody = mail.toJSON()
  var request = sg.emptyRequest()
  request.method = 'POST'
  request.path = '/v3/mail/send'
  request.body = requestBody
  sg.API(request, function (response) {
    console.log(response.statusCode)
    console.log(response.body)
    console.log(response.headers)
  })

After updating the helper, it would look more like this:

  var sg = require('sendgrid').SendGrid(process.env.SENDGRID_API_KEY)
  var emailHelper = require('sendgrid').mail(sg)
  emailHelper.setFrom("[email protected]")
  emailHelper.setTo("[email protected]")
  emailHelper.setSubject("Hello World from the SendGrid Node.js Library")
  emailHelper.setContent("text/plain", "some text here")
  emailHelper.sendEmail( function (response) {
      console.log(response.statusCode)
      console.log(response.body)
      console.log(response.headers)
   })

We would appreciate any additional feedback you may have. Thanks!

[kelkes]

So much breaking changes and the documentation is a big mess... how do you think one should use your service this way?
Why should i dig thru the source code only to send a simple template with substitution?

[thinkingserious]

Hello @kelkes,

Thanks for providing us with some feedback!

We are currently in the process of deciding what we need to improve in our next iteration. If you have specific suggestions (for example, which documentation are you referring to?), we would love to hear them. Either let us know here in this thread, or open separate issues describing what changes you would like to see.

One of the helpers we are considering building next is for templates, your voice would help make that happen.

With Best Regards,

Elmer

[silentroach]

https://docs.npmjs.com/misc/semver#prerelease-tags

[kelkes]

@thinkingserious
Thanks for your response.

I'm referring to this documentation https://github.com/sendgrid/sendgrid-nodejs/blob/master/USAGE.md
I cannot find (beside dive into the source code) how to send a template using substitution?

Also i find the whole thing way to low level for the default usecase. As a developer i almost never care about how your endpoints are designed as long as the emails get sent. :)
Whats the point of rewriting your node.js lib when things get more complicated for the users?

But nevermind. I will step back to 2.0 for now. prerelase tag is your friend here...

[thinkingserious]

Thank you @silentroach,

We went with a v3beta branch instead to incubate the beta, but perhaps we will consider the pre-release tag for future breaking changes.

Thank you @kelkes,

That is useful feedback.

Here is an example of how to send a "kitchen sink" v3 email using our helper: https://github.com/sendgrid/sendgrid-nodejs/blob/master/examples/helpers/mail/example.js#L15.

As to the thinking behind this low level release, this rewrite was a base implementation to support our new v3 /mail/send endpoint (a major advancement over v2) as well as the rest of the v3 Web API endpoints as fast as we could.

Now, we plan to iterate quickly based on your feedback, so thanks for making your voice heard and we will take your thoughts into consideration.

We will announcing our roadmap for this library using GitHub's milestone feature. Once we have made that update, we would love to hear your feedback.

With Best Regards,

Elmer