Naming of upload methods

[xsawyerx]

The convention for the method naming had been $verb_$noun like delete_comment(). With file uploading, this is a bit trickier because there are types. This creates a lot of different options:

upload_media_file(...); # since the uploadType is "media"
upload_file( 'media', ... ); # maybe just a general upload method with a parameter?
upload_simple_file(...); # in docs, Google also calls this a "simple upload"
simple_upload(...); # better English
simpe_file_upload(...); # the 'simple' now refers to the file instead of the upload

My position is best to keep it as upload_$uploadType_file() but I'm not sure it's the best format. FWIW, the other types after "simple upload" use the upload type, namely "multipart upload" (uploadType=multipart) and "resumable upload" (uploadType=resumable).

Maybe we should use the following?

upload_file_simple(...)
upload_file_multipart(...)
upload_file_resumable(...)

That might be better. But this would also only be using the uploadType in the second and third methods. The first method has an uploadType of media, not simple.

[xsawyerx]

Comparing different APIs by Google, it seems that:

• Java, Python, and Node.js seem to detect which form to use. We might be able to do the same. If there are body parameters, we'll use a multipart - otherwise, we use a simple ("media") upload.
• There are no examples of resumable uploads in any language, only in HTTP.

My suggestion so far:
(I'm leaving $gd object out of the examples for succinctness.)

# explicit uploadType
upload_media_file()
upload_multipart_file()

# general upload that tries to detect which to use
upload_file()

Resumable uploads are tricky and I haven't decided on their interface yet, but maybe:

my $upload_id = create_resumable_upload(...)
upload_file_content($upload_id, ...) # can be repeated for chunks
upload_file_content( $upload_id, 'chunk' => 2_000_000, ... ) # ask us to repeat in chunks of roughly 2M
resume_upload($upload_id, ...)