AIP for file upload and management

[zchenyu]

Would be nice to have an AIP guidance for how to handle resources that involve file input / output. Examples:

• A Job that have files as inputs and outputs
• A Book that stores files when created

[jankrynauw]

Some initial thoughts:

• Looking at say google drive api, there seems to be some insights on the above: https://developers.google.com/drive/api/reference/rest/v3/files/update
• Create / Update method have two versions: one for metadata and one for uploads
• what role does gRPC streaming play here?
• Singletons play a role when size matters, say a standard method GetFile() has a corresponding GetFileData(), perhaps even streaming?

Perhaps something along the lines of:

// Manages file operations.
service FileService {
  // Creates a new file.
  rpc CreateFile(CreateFileRequest) returns (File);

  // Gets a file.
  rpc GetFile(GetFileRequest) returns (File);

  // Updates a file.
  rpc UpdateFile(UpdateFileRequest) returns (File);

  // Deletes a file.
  rpc DeleteFile(DeleteFileRequest) returns (google.protobuf.Empty);

  // Lists files.
  rpc ListFiles(ListFilesRequest) returns (ListFilesResponse);

  // Gets file data.
  rpc GetFileData(GetFileDataRequest) returns (stream FileData);

  // Uploads file data using client-side streaming.
  rpc UploadFileData(stream UploadFileDataRequest) returns (UploadFileDataResponse);
}

// Response message for FileService.GetFileData.
message FileData {
  // A chunk of the file data.
  bytes data = 1;
}

// Request message for FileService.UploadFileData.
message UploadFileDataRequest {
  // The resource name of the file to upload data to.
  // Format: files/{file}
  string name = 1;

  // A chunk of the file data.
  bytes data = 2;
}

// Response message for FileService.UploadFileData.
message UploadFileDataResponse {
  // The size of the file in bytes after the upload.
  int64 size_bytes = 1;
}