Add apiResponses

[ryanseys]

Adding apiResponse to the callbacks of every API.

• BigQuery
• Datastore
• PubSub
• Storage
• Unit tests
• Regression tests (doesn't make sense)

Fixes #434

[stephenplusplus]

Looking clean so far 👍

[ryanseys]

Thanks! Do you think this is appropriate for datastore or what approach should we take there?

[stephenplusplus]

We do a lot of convenience wrapping of the response (all that entityTo___ stuff), so I think the decoded response will be the closest thing to a "raw" response.

[ryanseys]

TADA! 🎆 🚨

This PR should be ready for a review. This PR goes down in my books as one of the most tedious and boring PRs of all time. 😄

[ryanseys]

I plan to squash, but I figure it might be easier to review with the nice separate diffs.

[ryanseys]

I left out file#createReadStream and file#createWriteStream because there's many different types of responses or paths that can be taken where the apiResponses aren't really necessary. And we're dealing with responses that probably won't be any use to the end users. In your (@stephenplusplus) refactor of these methods, it might be nice to consider how the apiResponse objects could be returned with these methods.

[stephenplusplus]

@sindresorhus We've been designing gcloud-node to give users curated, massaged responses from their API calls. The upstream API response can be quite intimidating/non-user friendly, which is why we try to clean it up. However, we've hit a couple places where we forgot to include something and/or didn't want to include it, because it doesn't fit the majority use case. To support cases like these, we want to give users the raw API response in a "it's there if you need it, ignore it if you don't care" kind of way.

This PR is our solution, which tacks on that raw response as the final argument to their callback:

// old
bucket.upload('file.jpg', function (err, file) {});
// new
bucket.upload('file.jpg', function (err, file, apiResponse) {});

Quite a bit uglier, but we have methods that return more than just two arguments to the callback:

// old
dataset.get(key, function (err, results, nextQuery) {});
// new
dataset.get(key, function (err, results, nextQuery, apiResults) {});

I'm wondering if you've come across APIs that have solved for the same problem, and if our solution seems reasonable. Thanks!

[ryanseys]

Seems this has gotten out of sync with master. I'll rebase once we hear back from sindre.

[sindresorhus]

I'm wondering if you've come across APIs that have solved for the same problem, and if our solution seems reasonable. Thanks!

I guess that makes sense. I do that in my got module too, and so does request, albeit different order.

[stephenplusplus]

Cool, thanks!

Once the out of sync-ness is resolved, I think we're merge-ready.

[ryanseys]

Rebased and squashed. Merge when ready!

[stephenplusplus]

Yay!

[ryanseys]

Wewt!

[sunnychow]

thanks!