Comments (14)
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 anid
, 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.
Related Issues (20)
- Example project: WeTransfer x Twitter (bots)
- Implement unit tests for client and transfers HOT 1
- Add support for link items to SDK HOT 1
- Add support for blank transfers to the SDK
- Add support for async item adding to the SDK HOT 1
- Update Ruby SDK to get rid of meta when POSTing links HOT 1
- Add simplest use case possible for Transfer HOT 1
- Ruby SDK: instantiate Faraday just once
- Move file upload responsibility
- Move file completion responsibility
- Upload flow
- Sanitize filenames in Ruby SDK
- Implement deleting of files and links of a board
- split `create_transfer_and_upload_files` in 4 disparate parts
- `create_transfer` method accessible
- `upload_complete` for a file
- `part_number` isolated
- `finalize` a transfer
- Example project: WeTransfer x Messaging
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from wetransfer_ruby_sdk.