documentation is poor / lacking

[wardbt]

Issue Summary

I received the "we have a new version of the api" email and decided to upgrade. Certainly feels more like a downgrade to me. Before, sending email with the sendgrid-ruby gem was simple. Now it is not. I don't see how these changes benefit your customers (i.e. programmers trying to leverage sendgrid), it looks like you just wanted to refactor the code and then release a version that breaks everybody and then you provide poor documentation. You may like the code more this way but your customers (i.e. me) do not. Why don't you get your ego out of the way and stop writing code that serves you and write code that serves us. Regarding documentation, in your kitchen_sink example:

sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'], host: 'https://api.sendgrid.com')
response = sg.client.mail._('send').post(request_body: mail.to_json)
puts response.status_code
puts response.response_body
puts response.response_headers

I followed this and get:
undefined method `response_body' for #SendGrid::Response:0x005602531ef810

muppets...

Steps to Reproduce

1. This is the first step
2. This is the second step
3. Further steps, etc.

Any other information you want to share that is relevant to the issue being reported. Especially, why do you consider this to be a bug? What do you expect to happen instead?

Technical details:

• sendgrid-ruby Version: master (latest commit: [commit number])
• Ruby Version: 2.2

[thinkingserious]

Hello @wardbt,

I apologize for the typo in the mail helper example (correcting now), it should be:

puts response.body
puts response.headers

Thank you for taking the time to provide your feedback to us, we greatly appreciate it!

First, please note that the library does not currently completely reflect the fantastic jump in functionality and usability from v2 to v3 in the library (details here: https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/how_to_migrate_from_v2_to_v3_mail_send.html).

We took some steps back with this library to decouple it from the v2 mail send endpoint and provide support for all of the v3 Web API endpoints.

This is the first of many iterations and your feedback helps us prioritize what to iterate on next, so thanks again! We don't want to iterate without your feedback and we will continue to explore new methods to engage with you all.

We view our libraries as community driven and SendGrid led and shortly we will be publishing the current roadmap for this library here on GitHub where we will clarify the direction we want to go in hopes that people like you will continue to provide feedback.

Thanks again!

[wardbt]

How does one participate in this community that seems to be making the gem
harder and harder to use?

I can't believe what you've done with attachments... Speaking of that,
just experienced yet another breaking change around the Base64 encoding
which is now a requirement for attachments. Code that was working on
Friday no longer worked today:

Fridays code:

attach_content = Base64.encode64(File.open("some_file.pdf").read)

then this morning, got error 400's saying that the content must be
Base64 encoded... no announcement, nothing.. just breakage.. had to
change to:

attach_content = Base64.strict_encode64(File.open("some_file.pdf").read)

It's going to be very hard to trust this new API when it just breaks
all the time with no announcement... Have you no regard for your
customers? I suggest you find a new community to drive this because
your current one is going to bury your company IMO.

Postmark and AmazonSES are just a few clicks away and from experience,
their API's are a helluva simpler to use and get the job done. Why
should I use your ever changing, always breaking, poorly documented,
overly complex api?

On Fri, Jul 22, 2016 at 1:55 PM, Elmer Thomas notifications@github.com
wrote:

Hello @wardbt https://github.com/wardbt,

I apologize for the typo in the README (correcting now), it should be:

puts response.body
puts response.headers

Thank you for taking the time to provide your feedback to us, we greatly
appreciate it!

First, please note that the library does not currently completely reflect
the fantastic jump in functionality and usability from v2 to v3 in the
library (details here:
https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/how_to_migrate_from_v2_to_v3_mail_send.html
).

We took some steps back with this library to decouple it from the v2 mail
send endpoint and provide support for all of the v3 Web API endpoints.

This is the first of many iterations and your feedback helps us prioritize
what to iterate on next, so thanks again! We don't want to iterate without
your feedback and we will continue to explore new methods to engage with
you all.

We view our libraries as community driven and SendGrid led and shortly we
will be publishing the current roadmap for this library here on GitHub
where we will clarify the direction we want to go in hopes that people like
you will continue to provide feedback.

Thanks again!

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#79 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AGO_xf-5tq4fwFBeBpM4ZHuexpUbM6lZks5qYSBNgaJpZM4JTEUp
.

[thinkingserious]

@wardbt,

Thank you for taking the time to provide additional feedback.

Creating a helper for the attachment functionality in on the roadmap, thanks for the verification.

However, there should not have been a breaking change over the weekend. Generally, changes are announced in our CHANGELOG and in the releases section.

I'm guessing our API does not like the newlines that Base64.encode64 adds. But I'm not sure why on Friday it worked and not today. Is the issue consistent or does it vary with different attachments?

This is valuable information to know when implementing that attachment helper, thanks again! Also, I've reached out to our team to confirm.

Given that this is the first iteration of this new library, we expect a great deal of feedback on how we can improve. And indeed, we have received some excellent feedback (including yours), and we are very grateful!

Personally, I am very excited about the next few iterations and we will do our best to make you a happy SendGrid customer.

[thinkingserious]

@wardbt,

OK, so my theory was correct. When you use Base64.encode64 it adds newlines and our code does a mod4 check, causing a failure in some cases. We will hide this complexity behind the helper. You should not have to know or care about that.

Thanks again for letting us know!

If you don't mind, we like to reward these types of contributions with some swag. If you email us at dx@sendgrid.com with your mailing address and T-shirt size we would love to hook you up.