357 lines
9.8 KiB
Markdown
357 lines
9.8 KiB
Markdown
## API v0.1
|
|
[<< Home](https://git.akkerweb.nl/FarmMaps/Documentatie/wiki/Home)
|
|
|
|
FarmMaps is an asynchronous architecture, the API flow keeps this in mind.
|
|
The API expects that all data is already processed and available provided, for example through the normal FarmMaps flow.
|
|
|
|
For the currently available public FarmMaps API you can take a look at swagger: http://farmmaps.awtest.nl/swagger/index.html
|
|
|
|
**Input preperation**
|
|
* VRAPoten requires specific input which needs to be provided by the FarmMaps API or user interface.
|
|
* You can activate the VRAPotenTask with the Task API, passing the just created cropfield item code as a parameter.
|
|
* Users can upload their own soilmaps if needed. (in case of when FarmMaps has not processed the required data).
|
|
* The file API can be used for this.
|
|
|
|
**Users can poll the task api to see if a task is completed**
|
|
**This can be achieved with the task execution id obtained from calling the 'ItemTask' API.**
|
|
|
|
### API flow
|
|
* Authenticate User
|
|
* *Create cropfield through FarmMaps API (optioneel)*
|
|
* Item 'FOLDER' must be created for parent to cropfields.
|
|
* Item 'vnd.farmmaps.itemtype.cropfield' must be created with its data as specified in the api.
|
|
* Task 'vnd.farmmaps.task.workflow' needs to be executed to aggregate all needed data.
|
|
* This is an asynchronous process and can take a while before all data is collected in FarmMaps.
|
|
* Upload own soil data (optioneel)
|
|
* Task 'vnd.farmmaps.task.vrapoten' must be executed to create an appliance map.
|
|
* Task 'vnd.farmmaps.task.taskmap' must be executed to create a taskmap.
|
|
* Download item data (tiff of shape)
|
|
|
|
### Steps
|
|
###### Authentication
|
|
Farmmaps uses OpenID: https://auth0.com/docs/protocols/oidc/openid-connect-discovery
|
|
|
|
It is recommended to use a library to facilitate the authentication.
|
|
To get the openid configuration call the following url: http://accounts.awtest.nl/.well-known/openid-configuration
|
|
|
|
The user could also use the openid-configuration to handle authentication by themselves.
|
|
|
|
The token received needs to be used in the request header.
|
|
>'Authorization': 'bearer {token}'
|
|
|
|
The token can also easily be created through the swagger documentation:
|
|
https://farmmaps.awtest.nl/swagger/index.html
|
|
|
|
###### Create cropfield with FarmMaps API (optioneel)
|
|
If there aren't any relevant cropfields in FarmMaps for the creation of VRAPoten appliance maps, you can create them yourself by executing the following steps:
|
|
* Execute the following REST call to create the 'my_drive' item which contains the needed itemcode:
|
|
> Request
|
|
```
|
|
GET /api/v1/folders/my_drive
|
|
```
|
|
> Response 200 Succes
|
|
```javascript
|
|
{
|
|
"url": "string",
|
|
"code": "string",
|
|
"name": "string",
|
|
"created": "2019-12-18T09:49:35.741Z",
|
|
"updated": "2019-12-18T09:49:35.741Z",
|
|
"dataDate": "2019-12-18T09:49:35.741Z",
|
|
"itemType": "string",
|
|
"sourceTask": "string",
|
|
"size": 0,
|
|
"state": 0,
|
|
"thumbnail": true
|
|
}
|
|
```
|
|
|
|
* Create a 'FOLDER' item as a child of the 'my_drive' item.
|
|
>Request
|
|
```javascript
|
|
POST /api/v1/item
|
|
{
|
|
"parentCode": "{my_drive_code}",
|
|
"itemType": "FOLDER",
|
|
"name": "string",
|
|
"data": {},
|
|
"dataDate": "2019-12-18T09:59:18.893Z",
|
|
"geometry": {},
|
|
"tags": [
|
|
"string"
|
|
]
|
|
}
|
|
```
|
|
> Response 201 Created
|
|
```javascript
|
|
{
|
|
"parentCode": "string",
|
|
"geometry": {},
|
|
"data": {},
|
|
"tags": [
|
|
"string"
|
|
],
|
|
"url": "string",
|
|
"code": "string",
|
|
"name": "string",
|
|
"created": "2019-12-18T10:16:21.455Z",
|
|
"updated": "2019-12-18T10:16:21.455Z",
|
|
"dataDate": "2019-12-18T10:16:21.455Z",
|
|
"itemType": "string",
|
|
"sourceTask": "string",
|
|
"size": 0,
|
|
"state": 0,
|
|
"thumbnail": true
|
|
}
|
|
```
|
|
Response 401 Not authenticated
|
|
Response 403 No WRITE permissions in parent item
|
|
Response 404 Parent Item not found
|
|
|
|
* Create a 'vnd.farmmaps.itemtype.cropfield' item as a child of the 'FOLDER' item.
|
|
> Request
|
|
```javascript
|
|
POST /api/v1/item
|
|
{
|
|
"parentCode": "{FOLDER_item_code}",
|
|
"itemType": "vnd.farmmaps.itemtype.cropfield",
|
|
"name": "cropfield for VRA",
|
|
"dataDate": "2019-11-25",
|
|
"data": {},
|
|
"geometry": {"type":"Polygon","coordinates":[[[6.09942873984307,53.070025028087],[6.09992507404607,53.0705617890585],[6.10036959220086,53.0710679529031],[6.10065149010421,53.0714062774307],[6.10087493644271,53.0716712354474],[6.10091082982487,53.0716936039203],[6.10165087441291,53.0712041549161],[6.10204994718318,53.0709349338005],[6.10263143118855,53.0705789370018],[6.10311578125011,53.0702657538294],[6.10331686552072,53.0701314102389],[6.103326530575,53.070119463569],[6.10309137950343,53.0699829669055],[6.10184241586523,53.0692902201371],[6.10168497998891,53.0691984306747],[6.10092987659869,53.0694894453514],[6.09942873984307,53.070025028087]]]}
|
|
}
|
|
```
|
|
> Response 201 Created
|
|
```Javascript
|
|
{
|
|
"parentCode": "string",
|
|
"geometry": {},
|
|
"data": {},
|
|
"tags": [
|
|
"string"
|
|
],
|
|
"url": "string",
|
|
"code": "string",
|
|
"name": "string",
|
|
"created": "2019-12-18T10:16:21.455Z",
|
|
"updated": "2019-12-18T10:16:21.455Z",
|
|
"dataDate": "2019-12-18T10:16:21.455Z",
|
|
"itemType": "string",
|
|
"sourceTask": "string",
|
|
"size": 0,
|
|
"state": 0,
|
|
"thumbnail": true
|
|
}
|
|
```
|
|
|
|
* Execute the workflow task with the cropfield item code.
|
|
This steps makes sure that FarmMaps aggregates all needed data for the cropfield.
|
|
> Request
|
|
```javascript
|
|
POST /api/v1/items/{code}/tasks
|
|
{
|
|
"taskType": "vnd.farmmaps.task.workflow"
|
|
}
|
|
```
|
|
> Response 201
|
|
```javascript
|
|
{
|
|
"code": "string",
|
|
"taskType": "vnd.farmmaps.task.workflow",
|
|
"delay": "",
|
|
"attributes": {
|
|
"additionalProp1": "string",
|
|
"additionalProp2": "string",
|
|
"additionalProp3": "string"
|
|
}
|
|
}
|
|
```
|
|
Response 400 Tasktype not found
|
|
Response 401 Not authenticated
|
|
Response 403 No WRITE permissions in item
|
|
Response 404 Item not found
|
|
|
|
###### Uploading own data (optioneel)
|
|
If the user wants to upload custom data (lutum/ec) they can use the FarmMaps file API.
|
|
The API is based on the google drive API.
|
|
|
|
* Start request
|
|
|
|
> Request
|
|
```javascript
|
|
POST https://farmmaps.awacc.nl/api/v1/file
|
|
|
|
Host: farmmaps.awtest.nl
|
|
Authorization: Bearer < Token >
|
|
X-Upload-Content-Length: 13507747
|
|
X-Upload-Content-Type: application/x-zip-compressed
|
|
Content-Type: application/json; charset=UTF-8
|
|
Content-Length: 181
|
|
|
|
{
|
|
"name":"Grondsoorten2006-SHP.zip",
|
|
"mimeType":"application/x-zip-compressed",
|
|
"size":13507747,
|
|
"lastModified":1575293019617,
|
|
"parentCode":"c0787987a3f7449c97eecd6d015eb4c2:USER_FILES"
|
|
}
|
|
```
|
|
> Response
|
|
```javascript
|
|
Location: /api/v1/file/2831cd05ddc0415784930059c658db55
|
|
Content-Length: 194
|
|
Content-Type: application/json; charset=utf-8
|
|
|
|
{
|
|
"code":"2831cd05ddc0415784930059c658db55",
|
|
"chunks":1,
|
|
"parentCode":"c0787987a3f7449c97eecd6d015eb4c2:USER_FILES",
|
|
"name":"Grondsoorten2006-SHP.zip",
|
|
"size":13507747,
|
|
"chunkSize":13507747,
|
|
"data":{}
|
|
}
|
|
```
|
|
|
|
* Request upload chunk 1
|
|
|
|
> Request
|
|
```javascript
|
|
PUT https://farmmaps.awtest.nl/api/v1/file/2831cd05ddc0415784930059c658db55
|
|
|
|
Host: farmmaps.awtest.nl
|
|
Authorization: Bearer < Token >
|
|
Content-Type: application/octet-stream
|
|
Content-Length: 2097152
|
|
Content-Range: bytes 0-2097151/13507747
|
|
|
|
<data>
|
|
```
|
|
> Response
|
|
```javascript
|
|
HTTP/1.1 308 Resume Incomplete
|
|
|
|
Range: 0-2097151
|
|
Content-Length: 17
|
|
|
|
Resume Incomplete
|
|
```
|
|
|
|
* Request upload chunk 2
|
|
|
|
> Request
|
|
```javascript
|
|
PUT https://farmmaps.awtest.nl/api/v1/file/2831cd05ddc0415784930059c658db55
|
|
|
|
Host: farmmaps.awtest.nl
|
|
Authorization: Bearer < Token >
|
|
Content-Type: application/octet-stream
|
|
Content-Length: 2097152
|
|
Content-Range: bytes 2097152-4194303/13507747
|
|
|
|
<data>
|
|
```
|
|
> Response
|
|
```javascript
|
|
HTTP/1.1 308 Resume Incomplete
|
|
|
|
Range: 0-4194303
|
|
Content-Length: 17
|
|
|
|
Resume Incomplete
|
|
```
|
|
|
|
* Final request
|
|
|
|
> Request
|
|
```javascript
|
|
PUT https://farmmaps.awtest.nl/api/v1/file/2831cd05ddc0415784930059c658db55
|
|
|
|
Host: farmmaps.awtest.nl
|
|
Authorization: Bearer < Token >
|
|
Content-Type: application/octet-stream
|
|
Content-Length: 924835
|
|
Content-Range: bytes 12582912-13507746/13507747
|
|
|
|
<data>
|
|
```
|
|
> Response
|
|
```javascript
|
|
Upload response laatste chunk
|
|
|
|
HTTP/1.1 201 Created
|
|
|
|
Range: 0-13507746
|
|
Content-Length: 0
|
|
```
|
|
|
|
###### Creating appliance maps
|
|
Execute the VRAPotenTask with the item code of the cropfield as parameter inside {code}.
|
|
Use the input map code inside {itemCode}.
|
|
|
|
> Request
|
|
```javascript
|
|
POST /api/v1/items/{code}/tasks
|
|
{
|
|
"taskType": "vnd.farmmaps.task.vrapoten",
|
|
"attributes": {
|
|
"inputCode": "{itemCode}",
|
|
"meanDensity": "30",
|
|
"variation": "20"
|
|
}
|
|
}
|
|
```
|
|
> Response 201
|
|
```javascript
|
|
{
|
|
"code": "string",
|
|
"taskType": "vnd.farmmaps.task.workflow",
|
|
"delay": "",
|
|
"attributes": {
|
|
"additionalProp1": "string",
|
|
"additionalProp2": "string",
|
|
"additionalProp3": "string"
|
|
}
|
|
}
|
|
```
|
|
|
|
Response 400 Tasktype not found
|
|
Response 401 Not authenticated
|
|
Response 403 No WRITE permissions in item
|
|
Response 404 Item not found
|
|
|
|
###### Create taskmap
|
|
The user can use the "ItemTask" API to execute the TaskmapTask with the item code from the appliancemap in {code}.
|
|
|
|
> Request
|
|
```javascript
|
|
POST /api/v1/items/{code}/tasks
|
|
{
|
|
"taskType": "vnd.farmmaps.task.taskmap"
|
|
}
|
|
```
|
|
> Response 201
|
|
```javascript
|
|
{
|
|
"code": "string",
|
|
"taskType": "vnd.farmmaps.task.workflow",
|
|
"delay": "",
|
|
"attributes": {
|
|
"additionalProp1": "string",
|
|
"additionalProp2": "string",
|
|
"additionalProp3": "string"
|
|
}
|
|
}
|
|
```
|
|
|
|
Response 400 Tasktype not found
|
|
Response 401 Not authenticated
|
|
Response 403 No WRITE permissions in item
|
|
Response 404 Item not found
|
|
|
|
###### Data downloaden
|
|
In case the data is available in can be downloaded with the File API.
|
|
> Request
|
|
```javascript
|
|
GET /api/v1/items/{itemcode}/data
|
|
``` |