235 lines
7.0 KiB
Markdown
235 lines
7.0 KiB
Markdown
# Uploading a file
|
|
This page documents how to upload a file through the FarmMaps API.
|
|
The FarmMaps file upload API follows the [Google Drive API](https://developers.google.com/drive/api/v3/manage-uploads#resumable) loosely.
|
|
Files smaller than 2 MB are uploaded in a single part, larger files need to be split into parts of 1 MB.
|
|
|
|
The workflow for uploading a file is as follows:
|
|
* Register the file for upload.
|
|
* Uploading the file chunks
|
|
* Downloading the file to check (optional)
|
|
|
|
**Prerequisites**
|
|
- To be able to perform requests, make sure you have an [access token](Create-access-token.md).
|
|
|
|
### Registering the upload
|
|
Before a file can be uploaded it needs to be registered. Files smaller than 2 MB can be uploaded in one chunk.
|
|
Bigger files need to be uploaded in chunks of 1 MB. The uploaded files are structured in a hierarchy, so we'll specify a `parentCode` to identify its parent.
|
|
We'll first retrieve this parentcode using a GET request to the "my_drive" (root)folder.
|
|
|
|
**Request**
|
|
Replace `<acces token>` with your actual token.
|
|
```http
|
|
GET https://farmmaps.awacc.nl/api/v1/folders/my_drive? HTTP/1.1
|
|
Host: farmmaps.awacc.nl
|
|
Accept: application/json
|
|
Authorization: Bearer <access token>
|
|
```
|
|
|
|
**Response**
|
|
The response will be something similar to:
|
|
|
|
```http
|
|
HTTP/1.1 200 OK
|
|
Server: nginx/1.14.0 (Ubuntu)
|
|
Date: Tue, 21 Apr 2020 09:57:07 GMT
|
|
Content-Type: application/json; charset=utf-8
|
|
Transfer-Encoding: chunked
|
|
Connection: keep-alive
|
|
Cache-Control: no-store,no-cache
|
|
Pragma: no-cache
|
|
Content-Encoding: br
|
|
Vary: Accept-Encoding
|
|
|
|
```
|
|
|
|
So the `parentcode` we need is **"f25d8765a1cd407cb235961c73c268cf:USER_FILES"**
|
|
We can now register the file. In the request to register the upload, we specify its parent (`parentCode`),
|
|
the filename (`name`), and the size in bytes (`size`) in the body.
|
|
|
|
**Request**
|
|
|
|
```http
|
|
POST /api/v1/file HTTP/1.1
|
|
Accept: application/json
|
|
Authorization: Bearer <access token>
|
|
Content-Type: application/json
|
|
Cache-Control: no-cache
|
|
Host: farmmaps.awacc.nl
|
|
Accept-Encoding: gzip, deflate, br
|
|
Connection: keep-alive
|
|
Content-Length: 115
|
|
|
|
```
|
|
|
|
**Response**
|
|
If all went well, we should recieve a response with status code 201, indicating that a new file was registered.
|
|
```http
|
|
HTTP/1.1 201 Created
|
|
Server: nginx/1.14.0 (Ubuntu)
|
|
Date: Tue, 21 Apr 2020 10:08:56 GMT
|
|
Content-Type: application/json; charset=utf-8
|
|
Transfer-Encoding: chunked
|
|
Connection: keep-alive
|
|
Cache-Control: no-store,no-cache
|
|
Pragma: no-cache
|
|
Content-Encoding: br
|
|
Location: /api/v1/file/147357a252044a098788492729c4d551
|
|
Vary: Accept-Encoding
|
|
|
|
```
|
|
For files larger than 2 MB we also need to specify the chunksize (`chunkSize`):
|
|
```http
|
|
POST /api/v1/file HTTP/1.1
|
|
Accept: application/json
|
|
Authorization: Bearer <access token>
|
|
Content-Type: application/json
|
|
Cache-Control: no-cache
|
|
Host: farmmaps.awacc.nl
|
|
Accept-Encoding: gzip, deflate, br
|
|
Connection: keep-alive
|
|
Content-Length: 147
|
|
|
|
```
|
|
|
|
**Response**
|
|
The response now shows the amount of chunks that we'll need to send ("chunks":7).
|
|
```http
|
|
HTTP/1.1 201 Created
|
|
Server: nginx/1.14.0 (Ubuntu)
|
|
Date: Tue, 21 Apr 2020 14:27:05 GMT
|
|
Content-Type: application/json; charset=utf-8
|
|
Transfer-Encoding: chunked
|
|
Connection: keep-alive
|
|
Cache-Control: no-store,no-cache
|
|
Pragma: no-cache
|
|
Content-Encoding: br
|
|
Location: /api/v1/file/f319e9c6bfe3493cba1a888f6292f00a
|
|
Vary: Accept-Encoding
|
|
|
|
```
|
|
|
|
### Uploading the chunks
|
|
The upload URL contains the registration code, and ends with the chunk number.
|
|
The body of the request contains the data of the chunk. For uploading the first chunk, we can use the request below.
|
|
Subsequent chunks can be uploaded by increading the chunk number at the end and adding the next chunk in the body.
|
|
|
|
**Request**
|
|
```http
|
|
POST /api/v1/file/9c27d92fd44e43cf975275a2bec5c5f5/chunk/1 HTTP/1.1
|
|
Accept: application/json
|
|
Authorization: Bearer <access token>
|
|
Cache-Control: no-cache
|
|
Host: farmmaps.awacc.nl
|
|
Accept-Encoding: gzip, deflate, br
|
|
Connection: keep-alive
|
|
Content-Type: multipart/form-data; boundary=--------------------------272838473781934324854095
|
|
Content-Length: 1048788
|
|
----------------------------272838473781934324854095
|
|
Content-Disposition: form-data; name="Chunk"; filename="sampledata2_1.csv"
|
|
|
|
<sampledata2_1.csv>
|
|
----------------------------272838473781934324854095--
|
|
```
|
|
|
|
**Response**
|
|
The response should show a 200 status code, confirming that the chunk was recieved succesfully:
|
|
```http
|
|
HTTP/1.1 200 OK
|
|
Server: nginx/1.14.0 (Ubuntu)
|
|
Date: Tue, 21 Apr 2020 15:07:19 GMT
|
|
Content-Length: 0
|
|
Connection: keep-alive
|
|
Cache-Control: no-store,no-cache
|
|
Pragma: no-cache
|
|
```
|
|
|
|
When uploading the final chunk of the file a 201 status code should be returned.
|
|
This indicates all chunks have been uploaded. The file will now be ready for further processing.
|
|
|
|
```http
|
|
HTTP/1.1 201 Created
|
|
Server: nginx/1.14.0 (Ubuntu)
|
|
Date: Tue, 21 Apr 2020 15:21:01 GMT
|
|
Content-Type: application/json; charset=utf-8
|
|
Transfer-Encoding: chunked
|
|
Connection: keep-alive
|
|
Cache-Control: no-store,no-cache
|
|
Pragma: no-cache
|
|
Content-Encoding: br
|
|
Location: /api/v1/item/9c27d92fd44e43cf975275a2bec5c5f5
|
|
Vary: Accept-Encoding
|
|
```
|
|
|
|
### Downloading the uploaded file
|
|
To verify that your file was uploaded and re-assembled correctly you can download the file using a simple GET request.
|
|
|
|
```http
|
|
GET /api/v1/items/9c27d92fd44e43cf975275a2bec5c5f5/data HTTP/1.1
|
|
Accept: application/json
|
|
Authorization: Bearer <acces token>
|
|
Cache-Control: no-cache
|
|
Host: farmmaps.awacc.nl
|
|
Accept-Encoding: gzip, deflate, br
|
|
Connection: keep-alive
|
|
```
|
|
This will return the file as an attachment:
|
|
```http
|
|
HTTP/1.1 200 OK
|
|
Server: nginx/1.14.0 (Ubuntu)
|
|
Date: Tue, 21 Apr 2020 16:05:25 GMT
|
|
Content-Type: application/octet-stream
|
|
Content-Length: 0
|
|
Connection: keep-alive
|
|
Cache-Control: no-store,no-cache
|
|
Pragma: no-cache
|
|
Content-Disposition: attachment; filename=sampledata2.csv; filename*=UTF-8''sampledata2.csv
|
|
```
|
|
|
|
**Troubleshooting**
|
|
|Status code|Description|
|
|
|---|---|
|
|
|200|Chunk was uploaded|
|
|
|201|All chunks from file have been uploaded|
|
|
|400|Error: the chunk number exceeds the total number of chunks calculated earlier|
|
|
|401|Error: not authenticated|
|
|
|404|Error: the chunk cannot be added to a registered file (not found)| |