Transfer API
Transfers must be created with files. Once the transfer has been created and finalized, the transfer is locked and cannot be further modified.
Create a new transfer
When you create a transfer, you must include at least one file in the transfer create request.
+ +Creating a transfer is to inform the API that you want to create a transfer (with at least one file), but you aren't sending the files already.
+ +What you are sending is the message, a property that describes what this transfer is about, and a collection of file names and their size. This allows the API to set up a place where your files can be uploaded to in a later state. Make sure the size of the file is accurate. Please don't lie to us; we will not be able to handle your files in a later stage...
curl -i -X POST "https://dev.wetransfer.com/v2/transfers" \
-H "Content-Type: application/json" \
- -H "x-api-key: your_api_key" \
- -H "Authorization: Bearer jwt_token" \
- -d '{"message":"My very first transfer!","files":[
- {"name":"big-bobis.jpg", "size":195906}, "name":"kitty.jpg", "size":369785]}'
+ -H "x-api-key: REPLACE_WITH_YOUR_API_KEY" \
+ -H "Authorization: Bearer REPLACE_WITH_YOUR_TOKEN" \
+ -d '
+ {
+ "message":"My very first transfer!",
+ "files":[
+ {
+ "name":"big-bobis.jpg",
+ "size":195906
+ },
+ {
+ "name":"kitty.jpg",
+ "size":369785
+ }
+ ]
+ }'
const transfer = await wtClient.transfer.create({
message: 'My very first transfer!',
files: [
@@ -528,34 +543,41 @@ Headers
File size in bytes. Must be accurate. No fooling. Don't let us down!
Response
{
- "id": "random-hash",
- "message": "My very first transfer!",
- "state": "uploading",
- "files": [
+ "message" : "My very first transfer!",
+ "files" : [
{
- "id": "random-hash",
- "name": "big-bobis.jpg",
- "size": 195906,
- "multipart": {
- "part_numbers": 1,
- "chunk_size": 5242880
- }
+ "multipart" : {
+ "part_numbers" : 1,
+ "chunk_size" : 195906
+ },
+ "size" : 195906,
+ "type" : "file",
+ "name" : "big-bobis.jpg",
+ "id" : "c964caf6c54343f3b6e9610cb4ac5ea220181019143517"
},
{
- "id": "random-hash",
- "name": "kitty.jpg",
- "size": 369785,
- "multipart": {
- "part_numbers": 1,
- "chunk_size": 5242880
- }
+ "multipart" : {
+ "part_numbers" : 1,
+ "chunk_size" : 369785
+ },
+ "size" : 369785,
+ "type" : "file",
+ "id" : "e7f74773661f2be2bec90e6322864abd20181019143517",
+ "name" : "kitty.jpg"
}
- ]
+ ],
+ "url" : null,
+ "id" : "32a6ef6003f1429be0cf1674dd8fbdef20181019143517",
+ "state" : "uploading"
}
Creates a new transfer with specified files.
-Request upload URL
-To be able to upload a file, it must be split into parts and then each part will be uploaded to presigned AWS S3 URLs. This route can be used to fetch presigned upload URLS for each of a file's parts. These upload URLs are essentially limited access to a storage bucket hosted with Amazon. NB: They are valid for an hour and must be re-requested if they expire.
+Request upload URLs
+If you look at that response above, you see some pointers that are needed now. All files should be uploaded to a specific place. You just have to get the place from our API. To do that, you ask the API based on the transfer.id, each and every file.id, and for each part (based on the file.multipart.part_numbers property).
+
+To be able to upload a file, it must be split into parts and then each part will be uploaded to pre-signed AWS S3 URLs.
+
+This endpoint can be used to get pre-signed upload URLS for each of a file's parts. These upload URLs are essentially limited access to a storage bucket hosted with Amazon. NOTE: They are valid for an hour and must be re-requested if they expire.
curl -i -X GET "https://dev.wetransfer.com/v2/transfers/{transfer_id}/files/{file_id}/upload-url/{part_number}" \
-H "x-api-key: your_api_key" \
-H "Authorization: Bearer jwt_token"
@@ -635,17 +657,31 @@ Headers
<
"url": "https://presigned-s3-put-url"
}
-The Response Body contains the presigned S3 upload url.
+The Response Body contains the pre-signed S3 upload url.
404 (Not found)
-If the requester tries to request an upload URL for a file that is not in one of the requester's transfers, we will respond with 404 Not found.
-
+If you try to request an upload URL for a file that is not in the transfers, the API will respond with 404 Not found.
+{
+ "success" : false,
+ "message" : "Couldn't find FileObject"
+}
+
417 (Expectation Failed)
+If you request to upload part 0, our API will tell you that our parts are numbered for humans; we start counting at part 1:
+{
+ "success" : false,
+ "message" : "Chunk numbers are 1-based"
+}
+
File Upload
PUT {signed_url}
+Time to actually upload (chunks of) your file. With the pre-signed-upload-url you retrieved in the previous step, you can start uploading!
+
+You will interact directly with Amazon S3. As such, we have no control over the messages sent by S3.
+
Important: errors returned from S3 will be sent as XML, not JSON. If your response parser is expecting a JSON response it may throw an error here. Please see AWS' S3 documentation for more details about specific responses.
curl -i -T "./path/to/big-bobis.jpg" "https://signed-s3-upload-url"
-
// Use your favourite JS
+
// Use your favorite JS
const fs = require('fs');
const file = transfer.files[0];
@@ -678,7 +714,9 @@ PUT {signed_url}
Complete a file upload
-Finalize a file. Once all the parts have been uploaded succesfully, you use this endpoint to tell the system that it can start splicing the parts together to form one whole file.
+In the previous step, you've uploaded your file (potentially in parts) directly to S3. The WeTransfer API has no idea when that is complete. This call informs your transfer object that all the uploading for your file is done.
+
+Again, to inform the API about this event, you need both the transfer id and the file id. Not only that, you currently also have to inform this endpoint on the amount of part numbers.
curl -i -X PUT "https://dev.wetransfer.com/v2/transfers/{transfer_id}/files/{file_id}/upload-complete" \
-H "Content-Type: application/json" \
-H "x-api-key: your_api_key" \
@@ -743,10 +781,18 @@ Headers
<
"size": 195906,
"chunk_size": 195906
}
+417
+If you try to finalise a file, but didn't actually upload all chunks it will respond with something like this:
+{
+ "success": false,
+ "message": "Chunks 1 are still missing"
+}
Finalize a transfer
-Finalize the whole transfer. Once all the parts have been uploaded and finalized, you use this endpoint to tell the system that everything has been completely uploaded.
+After all files are uploaded and finalized, you can close the transfer for modification, and make it available for download.
+
+You do that by calling this endpoint. It informs the API that everything has been completely uploaded.
curl -i -X PUT "https://dev.wetransfer.com/v2/transfers/{transfer_id}/finalize" \
-H "Content-Type: application/json" \
-H "x-api-key: your_api_key" \
@@ -794,11 +840,13 @@ Headers
<
Yes
The public ID of the transfer where you added the files
-
Responses
200 (OK)
{
+
Responses
200 (OK)
+If all went well, the API sends you a lot of data. One of them being the url. That is the thing you will use to access the files in a browser.
+{
"id": "random-hash",
"state": "processing",
- "message": "Little kittens",
- "url": "https://we.tl/t-smaller-random-hash",
+ "message": "My first transfer!",
+ "url": "https://we.tl/t-12344657",
"files": [
{
"id": "random-hash",
@@ -813,12 +861,12 @@ Headers
<
}
400 (Bad Request)
This is returned if the transfer can no longer be written to, or is it ready to be downloaded.
403 (Unauthorized)
-When you try to access something you don't have access to.
+When you try to finalize a transfer you don't have access to.
Board API
The Board API is the latest addition to our Public API. It was originally built with our iOS and , Android apps in mind, but it's also suitable for web/desktop users. It is designed for collecting content rather than transmitting content from A to B (though it can do that, too). It supports both files and links. Boards can be changed - if you hold on to the board's public ID you are able to add and remove items from a board as long as it is live.
@@ -839,7 +887,7 @@ Create a new board
client = WeTransfer::Client.new(api_key: 'YOUR PRIVATE API KEY GOES HERE')
-board = client.create_board_and_upload_items(name: 'Kittens') do |builder|
+board = client.create_board_and_upload_items(name: 'Little kittens') do |builder|
builder.add_file(
name: 'bobis.jpg',
io: File.open('/path/to/kitty.jpg', 'rb')
@@ -906,9 +954,13 @@ Headers
"items": []
}
-
+
+
+Later you'll want to interact with your board. Add files and links to it. In order to do that, make sure to note the value of the id property.
Add links to a board
-Once a board has been created you can add links like so:
+A board can hold files and URLs. Lets have a look at how you can add URLs to your board. For that you need the id of the board you created earlier, unless your SDK will handle that for you.
+
+Once a board has been created you can add links like below:
curl -i -X POST "https://dev.wetransfer.com/v2/boards/{board_id}/links" \
-H "Content-Type: application/json" \
-H "x-api-key: your_api_key" \
@@ -1056,7 +1108,7 @@ Headers
<
"name": "big-bobis.jpg",
"size": 195906,
"multipart": {
- "id": "some.random-id--",
+ "id": "some random id",
"part_numbers": 1,
"chunk_size": 195906
},
@@ -1064,17 +1116,23 @@ Headers
<
}
]
-The endpoint will return an object for each file you want to add to the board. Each file must be split into chunks, and uploaded to a pre-signed S3 URL, provided by the following endpoint.
+The endpoint will return an object for each file you want to add to the board. The data returned is helpful in the next step when we want to request a place where we can upload our file.
+
+The important parts in the response are the id of the file, the id of the multipart object, together with its part_numbers.
Important
-Board chunks must be 6 megabytes in size, except for the very last chunk, which can be smaller. Sending too much or too little data will result in a 400 Bad Request error when you finalise the file.
+Board chunks must be 6 megabytes (or more precisely 6291456 bytes) in size, except for the very last chunk, which can be smaller. Sending too much or too little data will result in a 400 Bad Request error when you finalize the file. As with transfers: Do not let us down.
Request upload URL
+Now that you've informed us about the file(s) you want to upload, it is time to request upload URLs. Each chunk of the file has its own upload url.
+
GET /boards/{board_id}/files/{file_id}/upload-url/{part_number}/{multipart_upload_id}
-To be able to upload a file, it must be split into chunks, and uploaded to different presigned URLs. This route can be used to fetch presigned upload URLS for each of a file's parts. These upload URLs are essentially limited access to a storage bucket hosted with Amazon. They are valid for an hour and must be re-requested if they expire.
+To be able to upload a file, it must be split into chunks, and uploaded to different pre-signed URLs. This endpoint can be used to get pre-signed upload URLs for each of a file's parts. These upload URLs are essentially limited access to a storage bucket hosted with Amazon. They are valid for an hour and must be re-requested if they expire.
+
+Use the fields from the previous response; now you need the id of the file, the id of the multipart, and you must request a upload-url for all of your part_numbers.
curl -i -X GET "https://dev.wetransfer.com/v2/boards/{board_id}/files/{file_id}/upload-url/{part_number}/{multipart_upload_id}" \
-H "x-api-key: your_api_key" \
-H "Authorization: Bearer jwt_token"
@@ -1147,12 +1205,12 @@ GET /boards/{board_id}/files/{file_id}/upload-url/
The upload ID issued by AWS S3, which is available at multipart.id
Responses
200 (OK)
{
- "url": "https://presigned-s3-put-url"
+ "url": "https://a-very-long-pre-signed-s3-put-url"
}
-The Response Body contains the presigned S3 upload url.
+The response body contains the pre-signed S3 upload url. You will use that in the next step, when you upload the contents.
401 (Unauthorized)
-If the requester tries to request an upload URL for a file that is not in one of the requester's boards, we will respond with 401 UNAUTHORIZED.
+If you try to request an upload URL for a file that is not in one of your boards, the response will have a status code of 401 UNAUTHORIZED.
400 (Bad request)
If a request is made for a part, but no multipart_upload_id is provided; we will respond with a 400 BAD REQUEST as all consecutive parts must be uploaded with the same multipart_upload_id.
@@ -1160,7 +1218,7 @@ File Upload
PUT {signed_url}
-Please note: errors returned from S3 will be sent as XML, not JSON. If your response parser is expecting a JSON response it may throw an error here. Please see AWS' S3 documentation for more details about specific responses.
+You're communicating directly with Amazons' S3, not with our API. Please note: errors returned from S3 will be sent as XML, not JSON. If your response parser is expecting a JSON response it may throw an error here. Please see AWS' S3 documentation for more details about specific responses.
curl -i -T "./path/to/big-bobis.jpg" "https://signed-s3-upload-url"
const fs = require('fs');
@@ -1294,10 +1352,10 @@ GET /boards/{board_id}
{
"id": "random-hash",
"name": "kittie.gif",
- "size": 1024,
+ "size": 195906,
"multipart": {
"part_numbers": 1,
- "chunk_size": 1024
+ "chunk_size": 195906
},
"type": "file"
},
@@ -1312,8 +1370,11 @@ GET /boards/{board_id}
]
}
403 (Forbidden)
-If the requester tries to request a board that is not in one of the requester's boards, we will respond with 403 FORBIDDEN.
- {"success":false, "message":"This board does not belong to you"}
+If you try to request a board that is not yours, we will respond with 403 FORBIDDEN.
+{
+ "success":false,
+ "message":"This board does not belong to you"
+}
Errors
In working with the WeTransfer API you might come across some errors. Here are some of the most common, and what you can do about them.
Most common errors
@@ -1565,7 +1626,7 @@ Error codes
Create a new transfer
- Request upload URL
+ Request upload URLs
File Upload
diff --git a/docs/index.html.gz b/docs/index.html.gz
index f9cf74a..1bd089f 100644
Binary files a/docs/index.html.gz and b/docs/index.html.gz differ
diff --git a/docs/javascripts/all-2fffc1ac.js.gz b/docs/javascripts/all-2fffc1ac.js.gz
index ab8c7a7..b7ee4a6 100644
Binary files a/docs/javascripts/all-2fffc1ac.js.gz and b/docs/javascripts/all-2fffc1ac.js.gz differ
diff --git a/docs/javascripts/all_nosearch-e047639d.js.gz b/docs/javascripts/all_nosearch-e047639d.js.gz
index 34f0006..f640ea3 100644
Binary files a/docs/javascripts/all_nosearch-e047639d.js.gz and b/docs/javascripts/all_nosearch-e047639d.js.gz differ
diff --git a/docs/stylesheets/screen-e44caafe.css.gz b/docs/stylesheets/screen-e44caafe.css.gz
index 9a4a7ae..ea16409 100644
Binary files a/docs/stylesheets/screen-e44caafe.css.gz and b/docs/stylesheets/screen-e44caafe.css.gz differ
diff --git a/docs/v1/images/sdks/c-sharp-6c75ce29.svg.gz b/docs/v1/images/sdks/c-sharp-6c75ce29.svg.gz
index cfd9ede..96e35c9 100644
Binary files a/docs/v1/images/sdks/c-sharp-6c75ce29.svg.gz and b/docs/v1/images/sdks/c-sharp-6c75ce29.svg.gz differ
diff --git a/docs/v1/images/sdks/node-js-df9dffeb.svg.gz b/docs/v1/images/sdks/node-js-df9dffeb.svg.gz
index 4a94e0a..fa18fe7 100644
Binary files a/docs/v1/images/sdks/node-js-df9dffeb.svg.gz and b/docs/v1/images/sdks/node-js-df9dffeb.svg.gz differ
diff --git a/docs/v1/images/sdks/php-ab3973ac.svg.gz b/docs/v1/images/sdks/php-ab3973ac.svg.gz
index bf25b9e..b549b15 100644
Binary files a/docs/v1/images/sdks/php-ab3973ac.svg.gz and b/docs/v1/images/sdks/php-ab3973ac.svg.gz differ
diff --git a/docs/v1/images/sdks/python-dc794a59.svg.gz b/docs/v1/images/sdks/python-dc794a59.svg.gz
index ffa8a99..b983d42 100644
Binary files a/docs/v1/images/sdks/python-dc794a59.svg.gz and b/docs/v1/images/sdks/python-dc794a59.svg.gz differ
diff --git a/docs/v1/images/sdks/r-c8f72e0e.svg.gz b/docs/v1/images/sdks/r-c8f72e0e.svg.gz
index bc0c50e..e7f1140 100644
Binary files a/docs/v1/images/sdks/r-c8f72e0e.svg.gz and b/docs/v1/images/sdks/r-c8f72e0e.svg.gz differ
diff --git a/docs/v1/images/sdks/ruby-88f255a7.svg.gz b/docs/v1/images/sdks/ruby-88f255a7.svg.gz
index 1e04c6c..c687681 100644
Binary files a/docs/v1/images/sdks/ruby-88f255a7.svg.gz and b/docs/v1/images/sdks/ruby-88f255a7.svg.gz differ
diff --git a/docs/v1/images/sdks/swift-b38afa16.svg.gz b/docs/v1/images/sdks/swift-b38afa16.svg.gz
index b4285b8..00ff880 100644
Binary files a/docs/v1/images/sdks/swift-b38afa16.svg.gz and b/docs/v1/images/sdks/swift-b38afa16.svg.gz differ
diff --git a/docs/v1/index.html.gz b/docs/v1/index.html.gz
index 140301a..7c73074 100644
Binary files a/docs/v1/index.html.gz and b/docs/v1/index.html.gz differ
diff --git a/docs/v1/javascripts/all-71189092.js.gz b/docs/v1/javascripts/all-71189092.js.gz
index edafcfb..787c6b9 100644
Binary files a/docs/v1/javascripts/all-71189092.js.gz and b/docs/v1/javascripts/all-71189092.js.gz differ
diff --git a/docs/v1/javascripts/all_nosearch-0f98dbdc.js.gz b/docs/v1/javascripts/all_nosearch-0f98dbdc.js.gz
index ce59b2c..2a3d610 100644
Binary files a/docs/v1/javascripts/all_nosearch-0f98dbdc.js.gz and b/docs/v1/javascripts/all_nosearch-0f98dbdc.js.gz differ
diff --git a/docs/v1/stylesheets/screen-d3a39341.css.gz b/docs/v1/stylesheets/screen-d3a39341.css.gz
index 0c5307c..67cb1e6 100644
Binary files a/docs/v1/stylesheets/screen-d3a39341.css.gz and b/docs/v1/stylesheets/screen-d3a39341.css.gz differ
diff --git a/source/includes/_board-api.md b/source/includes/_board-api.md
index 2769e5b..2850ad1 100644
--- a/source/includes/_board-api.md
+++ b/source/includes/_board-api.md
@@ -29,7 +29,7 @@ const board = await wtClient.board.create({
client = WeTransfer::Client.new(api_key: 'YOUR PRIVATE API KEY GOES HERE')
-board = client.create_board_and_upload_items(name: 'Kittens') do |builder|
+board = client.create_board_and_upload_items(name: 'Little kittens') do |builder|
builder.add_file(
name: 'bobis.jpg',
io: File.open('/path/to/kitty.jpg', 'rb')
@@ -75,11 +75,15 @@ puts "The board can be viewed on #{board.url}"
}
```
-
+
+
+Later you'll want to interact with your board. Add files and links to it. In order to do that, make sure to note the value of the `id` property.
## Add links to a board
-Once a board has been created you can add links like so:
+A board can hold files *and* URLs. Lets have a look at how you can add URLs to your board. For that you need the `id` of the board you created earlier, unless your SDK will handle that for you.
+
+Once a board has been created you can add links like below:
```shell
curl -i -X POST "https://dev.wetransfer.com/v2/boards/{board_id}/links" \
@@ -194,7 +198,7 @@ const fileItems = await apiClient.board.addFiles(board, [{
"name": "big-bobis.jpg",
"size": 195906,
"multipart": {
- "id": "some.random-id--",
+ "id": "some random id",
"part_numbers": 1,
"chunk_size": 195906
},
@@ -203,17 +207,23 @@ const fileItems = await apiClient.board.addFiles(board, [{
]
```
-The endpoint will return an object for each file you want to add to the board. Each file must be split into chunks, and uploaded to a pre-signed S3 URL, provided by the following endpoint.
+The endpoint will return an object for each file you want to add to the board. The data returned is helpful in the next step when we want to request a place where we can upload our file.
+
+The important parts in the response are the `id` of the file, the `id` of the multipart object, together with its `part_numbers`.
**Important**
-Board chunks _must_ be 6 megabytes in size, except for the very last chunk, which can be smaller. Sending too much or too little data will result in a 400 Bad Request error when you finalise the file.
+Board chunks _must_ be 6 megabytes (or more precisely 6291456 bytes) in size, except for the very last chunk, which can be smaller. Sending too much or too little data will result in a `400 Bad Request` error when you finalize the file. As with transfers: Do not let us down.
Request upload URL
+Now that you've informed us about the file(s) you want to upload, it is time to request upload URLs. Each chunk of the file has its own upload url.
+
GET /boards/{board_id}/files/{file_id}/upload-url/{part_number}/{multipart_upload_id}
-To be able to upload a file, it must be split into chunks, and uploaded to different presigned URLs. This route can be used to fetch presigned upload URLS for each of a file's parts. These upload URLs are essentially limited access to a storage bucket hosted with Amazon. They are valid for an hour and must be re-requested if they expire.
+To be able to upload a file, it must be split into chunks, and uploaded to different pre-signed URLs. This endpoint can be used to get pre-signed upload URLs for each of a file's parts. These upload URLs are essentially limited access to a storage bucket hosted with Amazon. They are valid for an hour and must be re-requested if they expire.
+
+Use the fields from the previous response; now you need the `id` of the file, the `id` of the multipart, and you must request a upload-url for all of your `part_numbers`.
```shell
curl -i -X GET "https://dev.wetransfer.com/v2/boards/{board_id}/files/{file_id}/upload-url/{part_number}/{multipart_upload_id}" \
@@ -269,15 +279,15 @@ for (
```json
{
- "url": "https://presigned-s3-put-url"
+ "url": "https://a-very-long-pre-signed-s3-put-url"
}
```
-The Response Body contains the presigned S3 upload `url`.
+The response body contains the pre-signed S3 upload `url`. You will use that in the next step, when you upload the contents.
##### 401 (Unauthorized)
-If the requester tries to request an upload URL for a file that is not in one of the requester's boards, we will respond with 401 UNAUTHORIZED.
+If you try to request an upload URL for a file that is not in one of your boards, the response will have a status code of 401 UNAUTHORIZED.
##### 400 (Bad request)
@@ -287,7 +297,7 @@ If a request is made for a part, but no `multipart_upload_id` is provided; we wi
PUT {signed_url}
-Please note: errors returned from S3 will be sent as XML, not JSON. If your response parser is expecting a JSON response it may throw an error here. Please see AWS' S3 documentation for more details about specific responses.
+You're communicating directly with Amazons' S3, not with our API. Please note: errors returned from S3 will be sent as XML, not JSON. If your response parser is expecting a JSON response it may throw an error here. Please see AWS' S3 documentation for more details about specific responses.
```shell
curl -i -T "./path/to/big-bobis.jpg" "https://signed-s3-upload-url"
@@ -404,10 +414,10 @@ curl -i -X GET "https://dev.wetransfer.com/v2/boards/{board_id}" \
{
"id": "random-hash",
"name": "kittie.gif",
- "size": 1024,
+ "size": 195906,
"multipart": {
"part_numbers": 1,
- "chunk_size": 1024
+ "chunk_size": 195906
},
"type": "file"
},
@@ -425,8 +435,11 @@ curl -i -X GET "https://dev.wetransfer.com/v2/boards/{board_id}" \
##### 403 (Forbidden)
-If the requester tries to request a board that is not in one of the requester's boards, we will respond with 403 FORBIDDEN.
+If you try to request a board that is not yours, we will respond with 403 FORBIDDEN.
```json
- {"success":false, "message":"This board does not belong to you"}
+{
+ "success":false,
+ "message":"This board does not belong to you"
+}
```
diff --git a/source/includes/_sdks.md b/source/includes/_sdks.md
index fe7d1e3..ba827d1 100644
--- a/source/includes/_sdks.md
+++ b/source/includes/_sdks.md
@@ -2,8 +2,7 @@
## V2 and V1 Compatible SDKs
-These SDKs are or soon will be compatible with V1 and V2 of the WeTransfer API. Feel free to file
-issues or PRs to help them along! :)
+These SDKs are or soon will be compatible with V1 and V2 of the WeTransfer API. Feel free to file issues or PRs to help them along! :)
diff --git a/source/includes/_transfer-api.md b/source/includes/_transfer-api.md
index d4002a0..4ff6cbf 100644
--- a/source/includes/_transfer-api.md
+++ b/source/includes/_transfer-api.md
@@ -12,13 +12,29 @@ Transfers must be created with files. Once the transfer has been created and fin
When you create a transfer, you must include at least one file in the transfer create request.
+Creating a transfer is to inform the API that you want to create a transfer (with at least one file), but you aren't sending the files already.
+
+What you are sending is the `message`, a property that describes what this transfer is about, and a collection of file `name`s and their `size`. This allows the API to set up a place where your files can be uploaded to in a later state. Make sure the size of the file is accurate. Please don't lie to us; we will not be able to handle your files in a later stage...
+
```shell
curl -i -X POST "https://dev.wetransfer.com/v2/transfers" \
-H "Content-Type: application/json" \
- -H "x-api-key: your_api_key" \
- -H "Authorization: Bearer jwt_token" \
- -d '{"message":"My very first transfer!","files":[
- {"name":"big-bobis.jpg", "size":195906}, "name":"kitty.jpg", "size":369785]}'
+ -H "x-api-key: REPLACE_WITH_YOUR_API_KEY" \
+ -H "Authorization: Bearer REPLACE_WITH_YOUR_TOKEN" \
+ -d '
+ {
+ "message":"My very first transfer!",
+ "files":[
+ {
+ "name":"big-bobis.jpg",
+ "size":195906
+ },
+ {
+ "name":"kitty.jpg",
+ "size":369785
+ }
+ ]
+ }'
```
```javascript
@@ -82,37 +98,44 @@ puts "The transfer can be viewed on #{transfer.url}"
```json
{
- "id": "random-hash",
- "message": "My very first transfer!",
- "state": "uploading",
- "files": [
+ "message" : "My very first transfer!",
+ "files" : [
{
- "id": "random-hash",
- "name": "big-bobis.jpg",
- "size": 195906,
- "multipart": {
- "part_numbers": 1,
- "chunk_size": 5242880
- }
+ "multipart" : {
+ "part_numbers" : 1,
+ "chunk_size" : 195906
+ },
+ "size" : 195906,
+ "type" : "file",
+ "name" : "big-bobis.jpg",
+ "id" : "c964caf6c54343f3b6e9610cb4ac5ea220181019143517"
},
{
- "id": "random-hash",
- "name": "kitty.jpg",
- "size": 369785,
- "multipart": {
- "part_numbers": 1,
- "chunk_size": 5242880
- }
+ "multipart" : {
+ "part_numbers" : 1,
+ "chunk_size" : 369785
+ },
+ "size" : 369785,
+ "type" : "file",
+ "id" : "e7f74773661f2be2bec90e6322864abd20181019143517",
+ "name" : "kitty.jpg"
}
- ]
+ ],
+ "url" : null,
+ "id" : "32a6ef6003f1429be0cf1674dd8fbdef20181019143517",
+ "state" : "uploading"
}
```
Creates a new transfer with specified files.
-## Request upload URL
+## Request upload URLs
+
+If you look at that response above, you see some pointers that are needed now. All files should be uploaded to a specific place. You just have to get the place from our API. To do that, you ask the API based on the `transfer.id`, each and every `file.id`, and for each part (based on the `file.multipart.part_numbers` property).
+
+To be able to upload a file, it must be split into parts and then each part will be uploaded to pre-signed AWS S3 URLs.
-To be able to upload a file, it must be split into parts and then each part will be uploaded to presigned AWS S3 URLs. This route can be used to fetch presigned upload URLS for each of a file's parts. These upload URLs are essentially limited access to a storage bucket hosted with Amazon. NB: They are valid for an hour and must be re-requested if they expire.
+This endpoint can be used to get pre-signed upload URLS for each of a file's parts. These upload URLs are essentially limited access to a storage bucket hosted with Amazon. NOTE: They are valid for an **hour** and must be re-requested if they expire.
```shell
curl -i -X GET "https://dev.wetransfer.com/v2/transfers/{transfer_id}/files/{file_id}/upload-url/{part_number}" \
@@ -176,16 +199,38 @@ Transfer chunks must be 5 megabytes in size, except for the very last chunk, whi
}
```
-The Response Body contains the presigned S3 upload `url`.
+The Response Body contains the pre-signed S3 upload `url`.
##### 404 (Not found)
-If the requester tries to request an upload URL for a file that is not in one of the requester's transfers, we will respond with 404 Not found.
+If you try to request an upload URL for a file that is not in the transfers, the API will respond with 404 Not found.
+
+```json
+{
+ "success" : false,
+ "message" : "Couldn't find FileObject"
+}
+```
+
+##### 417 (Expectation Failed)
+
+If you request to upload part `0`, our API will tell you that our parts are numbered for humans; we start counting at part 1:
+
+```json
+{
+ "success" : false,
+ "message" : "Chunk numbers are 1-based"
+}
+```
File Upload
PUT {signed_url}
+Time to actually upload (chunks of) your file. With the pre-signed-upload-url you retrieved in the previous step, you can start uploading!
+
+You will interact directly with Amazon S3. As such, we have no control over the messages sent by S3.
+
Important: errors returned from S3 will be sent as XML, not JSON. If your response parser is expecting a JSON response it may throw an error here. Please see AWS' S3 documentation for more details about specific responses.
```shell
@@ -193,7 +238,7 @@ curl -i -T "./path/to/big-bobis.jpg" "https://signed-s3-upload-url"
```
```javascript
-// Use your favourite JS
+// Use your favorite JS
const fs = require('fs');
const file = transfer.files[0];
@@ -230,7 +275,9 @@ for (
Complete a file upload
-Finalize a file. Once all the parts have been uploaded succesfully, you use this endpoint to tell the system that it can start splicing the parts together to form one whole file.
+In the previous step, you've uploaded your file (potentially in parts) directly to S3. The WeTransfer API has no idea when that is complete. This call informs your transfer object that all the uploading for your file is done.
+
+Again, to inform the API about this event, you need both the transfer id and the file id. Not only that, you currently also have to inform this endpoint on the amount of part numbers.
```shell
curl -i -X PUT "https://dev.wetransfer.com/v2/transfers/{transfer_id}/files/{file_id}/upload-complete" \
@@ -280,9 +327,22 @@ await wtClient.transfer.completeFileUpload(transfer, file);
}
```
+##### 417
+
+If you try to finalise a file, but didn't actually upload all chunks it will respond with something like this:
+
+```json
+{
+ "success": false,
+ "message": "Chunks 1 are still missing"
+}
+```
+
Finalize a transfer
-Finalize the whole transfer. Once all the parts have been uploaded and finalized, you use this endpoint to tell the system that everything has been completely uploaded.
+After all files are uploaded and finalized, you can close the transfer for modification, and make it available for download.
+
+You do that by calling this endpoint. It informs the API that everything has been completely uploaded.
```shell
curl -i -X PUT "https://dev.wetransfer.com/v2/transfers/{transfer_id}/finalize" \
@@ -322,12 +382,14 @@ console.log(finalTransfer.url);
##### 200 (OK)
+If all went well, the API sends you a lot of data. One of them being the `url`. That is the thing you will use to access the files in a browser.
+
```json
{
"id": "random-hash",
"state": "processing",
- "message": "Little kittens",
- "url": "https://we.tl/t-smaller-random-hash",
+ "message": "My first transfer!",
+ "url": "https://we.tl/t-12344657",
"files": [
{
"id": "random-hash",
@@ -343,7 +405,7 @@ console.log(finalTransfer.url);
```
##### 400 (Bad Request)
@@ -352,4 +414,4 @@ This is returned if the transfer can no longer be written to, or is it ready to
##### 403 (Unauthorized)
-When you try to access something you don't have access to.
+When you try to finalize a transfer you don't have access to.
diff --git a/source/index.html.md b/source/index.html.md
index 7a0dcd2..bafb574 100644
--- a/source/index.html.md
+++ b/source/index.html.md
@@ -23,7 +23,7 @@ You can use our API to share files, links and love all over the world.
## Our APIs
-Depending on what you want to make we have two different APIs: transfers and boards.
+Depending on what you want to make we have two main tastes: **transfers** and **boards**.