storage: No additional query parameters apply-able --> library feels very limiting

[ryanseys]

Trying to upload a file with a predefinedAcl of 'publicRead' i.e. apply acl of allUsers = READABLE and owner has full access. This applies a simple query parameter to the request which we have no access to apply with the current library. I'm guessing this is by design but I can see a scenario in the future where a single developer is happily using this library and then wants to do something slightly outside the "norm" (where we decide what the norm is?) and therefore they can't use this library anymore to get the job done, so they abandon using this library. 😦

I mean, perhaps we could "open" this small functionality as:

bucket.write('filename.png', {
  data: data,
  metadata: {},
  public: true // will apply ?predefinedAcl=publicRead to URL
}, callback);

But the bigger question still remains:

How do we choose what to include and exclude from this library? Who decides what features exposed by the API make the cut in our library? Why would I ever choose to use gcloud in the first place if it's explicitly designed to leave out features that I don't know if I need to use yet?

[stephenplusplus]

I'm guessing this is by design

My guess would be we forgot 😊 Another guess, but I believe the goal is to provide 100% functionality, where we provide the easiest API possible to do the most common things, then allowing more verbose configuration objects where possible to handle not as common things.

[stephenplusplus]

As an example of more verbose configuration objects, here's what the write call could look like:

bucket.write('filename.png', {
  data: data,
  metadata: {},

  query: {
    predefinedAcl: 'publicRead'
  },

  request: {
    acl: [],
    cacheControl: []
  }
}, callback);

(Maybe query makes more sense renamed to request and request makes more sense named as body?)

Making a shortcut for public: true is nicer, however there are a lot of query options available when doing an insert. Favoring some by adding a shortcut could make our API confusing, but if it's common enough, I won't fight it.

Also, on this topic, our storage API needs an update method.

[ryanseys]

So if we exposed this functionality, we effectively have the same thing as google-api-nodejs-client with storage.bucket.insert(). Only datastore, not storage, uses protobuf as well so we aren't even gaining a smaller request footprint.

Seems datastore is where we are gaining the most help for developers with automatic transaction handling and protobuf support. Not sure how we gain much in this library for cloud storage compared to google-api-nodejs-client without sacrificing functionality.

We should be designing a specification of what methods we want this library to expose to the developer and what the equivalent method(s) would be if they used a generated tool such as google-api-nodejs-client.

[stephenplusplus]

I'll step aside to let others answer how we are meant to "compete" with the api client.

What I would consider a good goal for this client would be providing convenience methods, allowing access to underlying operations, while developing the app using maintainable, best practices, which will give us a platform to continue to grow, and add more features and optimizations going forward. This opens the doors for more contributions from users with use cases we haven't considered, and puts us in a better, focused OSS lifecycle.

We're really just providing a facade for API calls, and I think we're doing a pretty good job of making it more usable than alternatives. Again, the areas we need to improve will likely become more clear once we release 1.0 and get user feedback.

[ryanseys]

Predefined ACL support I believe is now working thanks to bucket#setMetadata but bucket ACL I don't believe is working yet (as defined by this resource and method) https://cloud.google.com/storage/docs/json_api/v1/bucketAccessControls/insert

[ryanseys]

This issue was pretty generic (my bad) but I'm going to close this now that ACL support has been merged into master in #304.