Add upload article and update home
This commit is contained in:
parent
bab8890042
commit
8f63248a6a
24
Home.md
24
Home.md
@ -47,18 +47,26 @@ For each request, the access token needs to be sent along. This access token pro
|
|||||||
To continue please see one of the articles below:
|
To continue please see one of the articles below:
|
||||||
|
|
||||||
- [Integrating FarmMaps Open ID Connect into your application](/wiki/Integrating-FarmMaps-OIDC)
|
- [Integrating FarmMaps Open ID Connect into your application](/wiki/Integrating-FarmMaps-OIDC)
|
||||||
- [Creating an access token for testing.](/wiki/Create-access-token.md)
|
- [Creating an access token for testing.](/wiki/Create-access-token)
|
||||||
|
|
||||||
## How to build a FarmMaps App
|
## Using the FarmMaps API
|
||||||
- Accessing the API
|
Once you have an access token, you can start querying the API.
|
||||||
- Uploading a file
|
A reference of the API can be found on [the swagger page](https://farmmaps.awacc.nl/swagger)
|
||||||
- Checking the file processing status
|
The API basics are uploading files, creating items and and running tasks to modify or convert data.
|
||||||
- Creating a crop field
|
For testing purposes, [Postman](https://www.postman.com) can be used to perform HTTP requests more easily.
|
||||||
- Pushing data to MQTT
|
|
||||||
|
|
||||||
|
We provide the following guides:
|
||||||
|
* [Uploading a file](/wiki/Upload-a-file)
|
||||||
|
* Creating a cropfield
|
||||||
|
* Running a task
|
||||||
|
|
||||||
|
Generally, tasks can be run in the same way.
|
||||||
|
However, each specific task has it's own inputs and properties.
|
||||||
|
How these work can be found in the use task examples below.
|
||||||
|
|
||||||
### Use-case examples
|
### Taks examples
|
||||||
* [VRAPoten-API](/wiki/VRAPoten-API)
|
* [VRAPoten-API](/wiki/VRAPoten-API)
|
||||||
* [VRANbs-API](/wiki/VRANbs-API)
|
* [VRANbs-API](/wiki/VRANbs-API)
|
||||||
* [VRAHerbicide-API](/wiki/VRAHerbicide-API)
|
* [VRAHerbicide-API](/wiki/VRAHerbicide-API)
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
233
Upload-a-file.md
Normal file
233
Upload-a-file.md
Normal file
@ -0,0 +1,233 @@
|
|||||||
|
# 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.
|
||||||
|
|
||||||
|
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](/wiki/Create-access-token).
|
||||||
|
|
||||||
|
### 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.
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
Replace `<acces token>` with your actual token.
|
||||||
|
```
|
||||||
|
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/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
|
||||||
|
|
||||||
|
{
|
||||||
|
"url":"/api/v1/folders/f25d8765a1cd407cb235961c73c268cf:USER_FILES",
|
||||||
|
"code":"f25d8765a1cd407cb235961c73c268cf:USER_FILES",
|
||||||
|
"name":"My Drive",
|
||||||
|
"created":"2019-09-25T19:39:33.841835",
|
||||||
|
"updated":"2019-09-25T19:39:33.841835",
|
||||||
|
"itemType":"ROOT_FOLDER",
|
||||||
|
"size":0,
|
||||||
|
"state":0,
|
||||||
|
"thumbnail":false
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
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**
|
||||||
|
|
||||||
|
```
|
||||||
|
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
|
||||||
|
|
||||||
|
{
|
||||||
|
"parentCode": "f25d8765a1cd407cb235961c73c268cf:USER_FILES",
|
||||||
|
"name": "example.csv",
|
||||||
|
"size": 67351
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
If all went well, we should recieve a response with status code 201, indicating that a new file was registered.
|
||||||
|
```
|
||||||
|
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
|
||||||
|
|
||||||
|
{
|
||||||
|
"code":"147357a252044a098788492729c4d551",
|
||||||
|
"chunks":1,
|
||||||
|
"parentCode":"f25d8765a1cd407cb235961c73c268cf:USER_FILES",
|
||||||
|
"name":"example.csv",
|
||||||
|
"size":67351,
|
||||||
|
"chunkSize":67351,
|
||||||
|
"data":{}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
For files larger than 2 MB we also need to specify the chunksize (`chunkSize`):
|
||||||
|
```
|
||||||
|
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
|
||||||
|
{
|
||||||
|
"parentCode": "f25d8765a1cd407cb235961c73c268cf:USER_FILES",
|
||||||
|
"name": "sampledata2.csv",
|
||||||
|
"size": 7265743,
|
||||||
|
"chunkSize": 1048576
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
The response now shows the amount of chunks that we'll need to send (`"chunks":7").
|
||||||
|
```
|
||||||
|
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
|
||||||
|
|
||||||
|
{
|
||||||
|
"code":"f319e9c6bfe3493cba1a888f6292f00a",
|
||||||
|
"chunks":7,
|
||||||
|
"parentCode":"f25d8765a1cd407cb235961c73c268cf:USER_FILES",
|
||||||
|
"name":"sampledata2.csv",
|
||||||
|
"size":7265743,
|
||||||
|
"chunkSize":1048576,
|
||||||
|
"data":{}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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**
|
||||||
|
```
|
||||||
|
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/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/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.
|
||||||
|
|
||||||
|
```
|
||||||
|
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/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)|
|
||||||
Loading…
Reference in New Issue
Block a user