FarmMaps/Documentatie
8
0
Fork 0
Code Pull Requests Releases Activity

Add upload article and update home

Browse Source
This commit is contained in:
Auke Sytsma 2020-04-21 18:33:31 +02:00
parent bab8890042
commit 8f63248a6a
2 changed files with 250 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
Home.md
View File

@ -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:
- [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
- Accessing the API
- Uploading a file
- Checking the file processing status
- Creating a crop field
- Pushing data to MQTT
## Using the FarmMaps API
Once you have an access token, you can start querying the API.
A reference of the API can be found on [the swagger page](https://farmmaps.awacc.nl/swagger)
The API basics are uploading files, creating items and and running tasks to modify or convert data.
For testing purposes, [Postman](https://www.postman.com) can be used to perform HTTP requests more easily.
We provide the following guides:
* [Uploading a file](/wiki/Upload-a-file)
* Creating a cropfield
* Running a task
### Use-case examples
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.
### Taks examples
* [VRAPoten-API](/wiki/VRAPoten-API)
* [VRANbs-API](/wiki/VRANbs-API)
* [VRAHerbicide-API](/wiki/VRAHerbicide-API)

233
Upload-a-file.md Normal file
View 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)|