RFC: Adding boards endpoint to SDK about wetransfer_ruby_sdk HOT 14 CLOSED

Thanks for writing this document! I like the separation between transfers and boards, however, from the interface's point of view, I have a few points to make:

• I don't see it very straight-forward to request an upload URL and then to complete files and transfers; couldn't this be handled by the SDK, behind curtains? The interface could look like:

  WeTransferClient.create_transfer(...) do |t|
    t.add_file(...)
  end
  

  or even

  WeTransferClient.create_transfer(...).with([files])
  

  This would assume that is the entire transfer and it will handle uploading everything by default.

• WeTransferClient.add_files(board:...) { |b| b.add_file_at ... looks way too verbose to me. Why not create/get the board first, and then add files on the resulting object? Something like:

  board = WeTransferClient.create_board(...)
  board.add_file(...)
  # or
  board.add_files([...])
  

• Not sure what WeTransferClient.upload_file(url: ,file_io: ) does. Does it create a transfer from a single file? What's the URL? If it's tied to a single file from a transfer...than I refer back to my first point, about the too-complicated API interface

from wetransfer_ruby_sdk.

Some questions/comments:

• WeTransferClient.create_board(name: 'title', description: 'description') method will return an object right?
• WeTransferClient.get_board(board: ) it's expecting a board object? I guess you want to pass an id, if you have already a board, why do you need to get it again?
• WeTransferClient.upload_file(url: ,file_io: ) method expects a url, is it the upload url? Because in that case, you need more than one to upload a file. Also, the client should not care about that, they should just provide a file a open a beer.
• WeTransferClient.request_upload_url(board: ,file: ,part_number: ) Which are the argument types? Objects, strings...?

from wetransfer_ruby_sdk.

WeTransferClient.create_board(name: 'title', description: 'description') method will return an object right?

All the methods return the Full board/transfer as an Object

WeTransferClient.get_board(board: ) it's expecting a board object? I guess you want to pass an id

Yes, an Id alone could also work.

WeTransferClient.upload_file(url: ,file_io: ) method expects a url, is it the upload url? Because in that case, you need more than one to upload a file. Also, the client should not care about that, they should just provide a file a open a beer.

A work around could be that we do the chunking inside the SDK, but i think that will result in a time-out on larger files, for that reason we could make the client responsible.

WeTransferClient.request_upload_url(board: ,file: ,part_number: ) Which are the argument types? Objects, strings...?

I'll add it to the methods

I don't see it very straight-forward to request an upload URL and then to complete files and transfers; couldn't this be handled by the SDK, behind curtains? The interface could look like:

In the current version we used to do everything behind the curtains, which is fine if you use it as a CLI. But if you want to use it on a server, this would lead into server timeouts for larger files.

WeTransferClient.add_files(board:...) { |b| b.add_file_at ... looks way too verbose to me. Why not create/get the board first, and then add files on the resulting object? Something like:

Nice addition, i'll wait for other comments and will value one over the other. The suggestion now is to keep the existing flow in place

Not sure what WeTransferClient.upload_file(url: ,file_io: ) does. Does it create a transfer from a single file? What's the URL? If it's tied to a single file from a transfer...than I refer back to my first point, about the too-complicated API interface

We could simplify this, but i think it will be an issue on larger files as noted before. If not please provide a how-to

from wetransfer_ruby_sdk.

[..] and then add files on the resulting object? Something like: [..]

To add an alternative; I think what also would be nice is:

WeTransferClient.create_board(...) do |board|
  board.add_file(...)
  board.add_url(...)
end

I don't really value one over the other though, I'll leave it up to your (= API team's) good judgement. 😅

from wetransfer_ruby_sdk.

WeTransferClient.upload_file(url: ,file_io: ) method expects a url, is it the upload url? Because in that case, you need more than one to upload a file. Also, the client should not care about that, they should just provide a file a open a beer.

A work around could be that we do the chunking inside the SDK, but i think that will result in a time-out on larger files, for that reason we could make the client responsible.

My point here is that we have at least two use cases here: when the SDK is been used as a CLI or as a part of a web server.

In the first case, we should handle everything. A user should just specify a transfer/board and a file, and we do the magic. No timeouts hire, more than the ones from the API.

For the second case, you don't want to have access to the files, but instead, give the client a URL where they should upload the chunks. Take wetransfer.com as an example ;) We could argue that we want to offer that options to our clients, but it will immediately backfire because regular web hostings suck, and will reject big files, or timeout. What we can do is provide examples on how to use the SDK on Rails + JS code.

from wetransfer_ruby_sdk.

I agree with @grdw 's point -- if we want to reflect all possibilities, we could have a method create_board either with or without a block; with a block, you can call b.add_file(...) etc. inside it, without a block it just creates an empty board. Same thing for adding items to an existing board: board.add_items with a block where you call b.add_file and/or b.add_url as many times as it is necessary.

Are we also considering more general endpoints to get all the boards who belong to the same user? How does the API deal with user tokens? E.g. how can the APIClient ask for GET /v1/collections for example?

from wetransfer_ruby_sdk.

I suspect we may in fact want to be explicit about this not being a CLI, since a CLI is something we already provide. Obviously if someone wants to build their own CLI in ruby using the SDK that's wonderful, and they can handle the magic themselves. ✨

from wetransfer_ruby_sdk.

On a more trivial note: we should be sure to include the user_identifier in the board method(s) (and the transfers also...?) as that will or should be mandatory in this new version of the API.

from wetransfer_ruby_sdk.

What is the deadline for responses on this RFC?

from wetransfer_ruby_sdk.

Depends on the discussion, but please submit your suggestions/feedback before 23 Augustus EOD.

from wetransfer_ruby_sdk.

I am asking for a 1-week extension to the RFC deadline then.

from wetransfer_ruby_sdk.

I'll close this RFC before todays backend meetup.

from wetransfer_ruby_sdk.

In that case I gotta be quick 😄

I think the proposed API for boards is simply not nice. There is still no concept of an "editing operation". In the given example:

WeTransferClient.add_files(board: new_board) do |b|
  b.add_file_at(path: '/path/to/another/local/file.jpg')
  b.add_file(name: 'README.txt', io: StringIO.new("This is the contents of the file"))
end

Why does it have to be a new_board? Why isn't it possible to add to an already existing board?
What would happen if I call add_link inside of an add_files method call block?

WeTransferClient.add_links(board: [Object]) do |b|
  b.add_link(url: "https://www.the.url.you.want.to.share.com", title: "title of the url"))
end

What happens if I call add_file inside of an add_links block? Basically I think you need to specify a correct way to retrieve a previously created board, and then if you want to permit semi-quasi-kinda-atomic change flows on that board you should probably have a method on the board itself, something like:

board.create_version do |builder|
  builder.add_file(....)
  builder.add_link(...)
  builder.add_paper_canvas(...)
end

or

WtTransferClient.modify_board(board) do |editable|
  editable.add_file(...)

In terms of transfers I think we should stick rigorously to the terminology we use inside the product already. So instead of

WeTransferClient.create_transfer(name: [String] ,description: [String]) 

you need

WeTransferClient.create_link_transfer(message: [String|nil]) 

Also transfers do not support titles. At all.

Initially when I did a spike on the SDK I wanted to package as much stuff into the module itself as possible - since the number of methods we needed to support was relatively small. But with the proposed expansions:

WeTransferClient.upload_file(upload_url: [String] ,file_io: [File])
Complete file: WeTransferClient.complete_file(transfer_id: [String] ,file_id: [String] )
Complete transfer WeTransferClient.complete_transfer

you are growing a whole "grape" of standalone methods and forcing the user of the API to manually pick out the necessary details from responses and feed those details (upload URLs, IDs and whatnot) to those standalone client methods. I would suggest instead designing the API around "remote handles" that you are able to serialize and restore from the API endpoint - like a Board object, a Transfer object and so forth. This will allow you to attach the necessary calls to the "remote object handle" itself and this, in turn, will permit removing potential for mistakes on the user's part. You don't have to store a lot in this remote handle - just the endpoint, some credential identifier for accessing it and the ID to retrieve it will do. APIv2 already allows this full on, for Spaceship you will need to go through some steps to make it available - but it is going to be worth it.
Ruby is not Elixir and not JS - classes and objects actually work.

from wetransfer_ruby_sdk.

Closed.
I'll keep all the suggestions in mind.
We have a PR open on the docs: here
and example bash scripts can be found here

from wetransfer_ruby_sdk.