Update 'VRAHerbicide-API.md'
Improved herbicide documentation with latest changesmaster
parent
5b72805644
commit
17498e26cf
|
|
@ -1,173 +1,204 @@
|
|||
## VRAHerbicide API
|
||||
[<< Home](README.md)
|
||||
|
||||
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 (frontend).
|
||||
|
||||
For the currently available public FarmMaps API you can take a look at swagger: http://farmmaps.awtest.nl/swagger/index.html
|
||||
|
||||
**Input preperation**
|
||||
* Users can upload their own data if needed. (in case of when FarmMaps has not processed the required data).
|
||||
* The farmmaps 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.**
|
||||
[Poll task status](Polling-task-status.md)
|
||||
|
||||
**Users can query the API for child items of a cropfield to see what items it has.**
|
||||
|
||||
### API flow
|
||||
* Authenticate User
|
||||
* Optional steps
|
||||
* *Create cropfield through FarmMaps API*
|
||||
* Item 'vnd.farmmaps.itemtype.cropfield' must be created with its data as specified in the api.
|
||||
* Task 'vnd.farmmaps.task.workflow' can be executed if needed 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 data*
|
||||
* IF shape data, convert to geotiff.
|
||||
* Querying predefined herbicide agents (for input constants if none available beforehand)
|
||||
* Task 'vnd.farmmaps.task.vraherbicide' must be executed to create an application map.
|
||||
* Task 'vnd.farmmaps.task.taskmap' can be executed to create a taskmap.
|
||||
* Download item data (tiff of shape)
|
||||
|
||||
### Steps
|
||||
[Authentication](Authentication.md)
|
||||
|
||||
##### Optional
|
||||
[Create Cropfield](Create-Cropfield.md)
|
||||
[Upload Data](Upload-Data.md)
|
||||
|
||||
###### Transform shape to geotiff
|
||||
The VRAHerbicide task only processes tiff items as input.
|
||||
If your input data is a processed shape file it first needs to be converted to geotiff, this can be done with the 'ShapeToGeoTiffTask'.
|
||||
|
||||
Pass the code of the shape item into the {code} parameter, this creates a new item with tiff data as the parent of the shape item.
|
||||
This new geotiff item should be used as input to the a task.
|
||||
|
||||
> Request
|
||||
```javascript
|
||||
POST /api/v1/items/{code}/tasks
|
||||
{
|
||||
"taskType": "vnd.farmmaps.task.shapetogeotiff"
|
||||
}
|
||||
```
|
||||
> Response 201
|
||||
```javascript
|
||||
{
|
||||
"code": "string",
|
||||
"taskType": "vnd.farmmaps.task.shapetogeotiff"
|
||||
}
|
||||
```
|
||||
|
||||
Response 400 Tasktype not found
|
||||
Response 401 Not authenticated
|
||||
Response 403 No WRITE permissions in item
|
||||
Response 404 Item not found
|
||||
|
||||
###### Querying predefined herbicide agents.
|
||||
A list of herbicide agents can be requested by finding the "vnd.farmmaps.package.vra.herbicide" items, taking the first item found and reading it's data field 'agents' array content.
|
||||
> Request
|
||||
```javascript
|
||||
GET /api/v1/items/?it=vnd.farmmaps.package.vra.herbicide
|
||||
```
|
||||
> Response 201
|
||||
```javascript
|
||||
{
|
||||
"code": "....",
|
||||
"data": {
|
||||
"agents": [
|
||||
{
|
||||
"name": "Liberator",
|
||||
"SoilType": "Dalgrond",
|
||||
"ExtraInputType": "Lutum",
|
||||
"MinDosis": 2,
|
||||
"MaxDosis": 3,
|
||||
"A": 0.1428,
|
||||
"B": 1.285714,
|
||||
"C": 1,
|
||||
"D": 97,
|
||||
"E": 3,
|
||||
"P": 1,
|
||||
"Crop": "Zetmeelaardappelen"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Response 400 Itemtype not found
|
||||
Response 401 Not authenticated
|
||||
Response 403 No READ permissions in item
|
||||
Response 404 Items not found
|
||||
|
||||
###### Creating an application map with the VRAHerbicide task
|
||||
Execute the task with the item code of the cropfield as parameter inside {code}.
|
||||
Use the input map code inside {itemCode}, specifying an inputCode for the input data item.
|
||||
|
||||
{itemCode} needs the code of the data input item passed into it.
|
||||
An **optional** {extraItemCode} can be passed inside the 'extraInputcode' field to process herbicide from 2 inputs.
|
||||
Fill in the agent field with an agent gotten from the herbicide agents query discussed above.
|
||||
|
||||
The resulting application map will be created as a child item of the cropfield item (this can be queried).
|
||||
> Request
|
||||
```javascript
|
||||
POST /api/v1/items/{code}/tasks
|
||||
{
|
||||
"taskType": "vnd.farmmaps.task.vraherbicide",
|
||||
"attributes": {
|
||||
"inputCode": "{itemCode}",
|
||||
"extraInputCode": "{extraItemCode}",
|
||||
"agent": {
|
||||
"SoilType": "Dalgrond",
|
||||
"ExtraInputType": "Lutum",
|
||||
"MinDosis": 2,
|
||||
"MaxDosis": 3,
|
||||
"A": 0.1428,
|
||||
"B": 1.285714,
|
||||
"C": 1,
|
||||
"D": 97,
|
||||
"E": 3,
|
||||
"P": 1,
|
||||
"Crop": "Zetmeelaardappelen"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
> Response 201
|
||||
```javascript
|
||||
{
|
||||
"code": "string", // code of task operation, can be queried for status
|
||||
"taskType": "vnd.farmmaps.task.vraherbicide",
|
||||
"attributes": {
|
||||
"inputCode": "{itemCode}",
|
||||
"extraInputCode": "{extraItemCode}",
|
||||
"agent": {
|
||||
"SoilType": "Dalgrond",
|
||||
"ExtraInputType": "Lutum",
|
||||
"MinDosis": 2,
|
||||
"MaxDosis": 3,
|
||||
"A": 0.1428,
|
||||
"B": 1.285714,
|
||||
"C": 1,
|
||||
"D": 97,
|
||||
"E": 3,
|
||||
"P": 1,
|
||||
"Crop": "Zetmeelaardappelen"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Response 400 Tasktype not found
|
||||
Response 401 Not authenticated
|
||||
Response 403 No WRITE permissions in item
|
||||
Response 404 Item not found
|
||||
|
||||
##### Create taskmap
|
||||
[Create Taskmap](Create-Taskmap.md)
|
||||
|
||||
##### Download the data
|
||||
In case the data is available it can be downloaded with the items API.
|
||||
> Request
|
||||
```javascript
|
||||
GET /api/v1/items/{itemcode}/download
|
||||
## VRAHerbicide API
|
||||
[<< Home](README.md)
|
||||
|
||||
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 (frontend).
|
||||
|
||||
For the currently available public FarmMaps API you can take a look at swagger: http://farmmaps.awtest.nl/swagger/index.html
|
||||
|
||||
**Input preperation**
|
||||
* Users can upload their own data if needed. (in case of when FarmMaps has not processed the required data).
|
||||
* The farmmaps 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.**
|
||||
[Poll task status](Polling-task-status.md)
|
||||
|
||||
**Users can query the API for child items of a cropfield to see what items it has.**
|
||||
|
||||
### API flow
|
||||
* Authenticate User
|
||||
* Optional steps
|
||||
* *Create cropfield through FarmMaps API*
|
||||
* Item 'vnd.farmmaps.itemtype.cropfield' must be created with its data as specified in the api.
|
||||
* Task 'vnd.farmmaps.task.workflow' can be executed if needed 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 data*
|
||||
* IF shape data, convert to geotiff.
|
||||
* Querying predefined herbicide agents (for input constants if none available beforehand)
|
||||
* Task 'vnd.farmmaps.task.vraherbicide' must be executed to create an application map.
|
||||
* Task 'vnd.farmmaps.task.taskmap' can be executed to create a taskmap.
|
||||
* Download item data (tiff of shape)
|
||||
|
||||
### Steps
|
||||
[Authentication](Authentication.md)
|
||||
|
||||
##### Optional
|
||||
[Create Cropfield](Create-Cropfield.md)
|
||||
[Upload Data](Upload-Data.md)
|
||||
|
||||
###### Transform shape to geotiff
|
||||
The VRAHerbicide task only processes tiff items as input.
|
||||
If your input data is a processed shape file it first needs to be converted to geotiff, this can be done with the 'ShapeToGeoTiffTask'.
|
||||
|
||||
Pass the code of the shape item into the {code} parameter, this creates a new item with tiff data as the parent of the shape item.
|
||||
This new geotiff item should be used as input to the a task.
|
||||
|
||||
> Request
|
||||
```javascript
|
||||
POST /api/v1/items/{code}/tasks
|
||||
{
|
||||
"taskType": "vnd.farmmaps.task.shapetogeotiff"
|
||||
}
|
||||
```
|
||||
> Response 201
|
||||
```javascript
|
||||
{
|
||||
"code": "string",
|
||||
"taskType": "vnd.farmmaps.task.shapetogeotiff"
|
||||
}
|
||||
```
|
||||
|
||||
Response 400 Tasktype not found
|
||||
Response 401 Not authenticated
|
||||
Response 403 No WRITE permissions in item
|
||||
Response 404 Item not found
|
||||
|
||||
###### Querying predefined herbicide agents.
|
||||
A list of herbicide agents can be requested by finding the "vnd.farmmaps.package.vra.herbicide" items, taking the first item found and reading it's data field 'agents' array content.
|
||||
> Request
|
||||
```javascript
|
||||
GET /api/v1/items/?it=vnd.farmmaps.package.vra.herbicide
|
||||
```
|
||||
> Response 201
|
||||
```javascript
|
||||
{
|
||||
"code": "....",
|
||||
"data": {
|
||||
"agents": [
|
||||
{
|
||||
"name": "Liberator",
|
||||
"SoilType": "Dalgrond",
|
||||
"ExtraInputType": "Lutum",
|
||||
"MinDosis": 2,
|
||||
"MaxDosis": 3,
|
||||
"A": 0.1428,
|
||||
"B": 1.285714,
|
||||
"C": 1,
|
||||
"D": 97,
|
||||
"E": 3,
|
||||
"P": 1,
|
||||
"Crop": "Zetmeelaardappelen"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Response 400 Itemtype not found
|
||||
Response 401 Not authenticated
|
||||
Response 403 No READ permissions in item
|
||||
Response 404 Items not found
|
||||
|
||||
###### Creating an application map with the VRAHerbicide task
|
||||
Execute the task with the item code of the cropfield as parameter inside {code}.
|
||||
Use the input map code inside {itemCode}, specifying an inputCode for the input data item.
|
||||
|
||||
{itemCode} needs the code of the data input item passed into it.
|
||||
An **optional** {extraItemCode} can be passed inside the 'extraInputcode' field to process herbicide from 2 inputs.
|
||||
Fill in the agent field with an agent gotten from the herbicide agents query discussed above.
|
||||
|
||||
The resulting application map will be created as a child item of the cropfield item (this can be queried).
|
||||
> Request
|
||||
```javascript
|
||||
POST /api/v1/items/{code}/tasks
|
||||
{
|
||||
"taskType": "vnd.farmmaps.task.vraherbicide",
|
||||
"attributes": {
|
||||
"inputCode": "{itemCode}",
|
||||
"extraInputCode": "{extraItemCode}",
|
||||
"agent": {
|
||||
"SoilType": "Dalgrond",
|
||||
"ExtraInputType": "Lutum",
|
||||
"MinDosis": 2,
|
||||
"MaxDosis": 3,
|
||||
"A": 0.1428,
|
||||
"B": 1.285714,
|
||||
"C": 1,
|
||||
"D": 97,
|
||||
"E": 3,
|
||||
"P": 1,
|
||||
"Crop": "Zetmeelaardappelen"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
> Response 201
|
||||
```javascript
|
||||
{
|
||||
"code": "string", // code of task operation, can be queried for status
|
||||
"taskType": "vnd.farmmaps.task.vraherbicide",
|
||||
"attributes": {
|
||||
"inputCode": "{itemCode}",
|
||||
"extraInputCode": "{extraItemCode}",
|
||||
"agent": {
|
||||
"SoilType": "Dalgrond",
|
||||
"ExtraInputType": "Lutum",
|
||||
"MinDosis": 2,
|
||||
"MaxDosis": 3,
|
||||
"A": 0.1428,
|
||||
"B": 1.285714,
|
||||
"C": 1,
|
||||
"D": 97,
|
||||
"E": 3,
|
||||
"P": 1,
|
||||
"Crop": "Zetmeelaardappelen"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Response 400 Tasktype not found
|
||||
Response 401 Not authenticated
|
||||
Response 403 No WRITE permissions in item
|
||||
Response 404 Item not found
|
||||
|
||||
##### Optional input parameters #####
|
||||
There are some optional task attribute input parameters for greater flexibility.
|
||||
|
||||
* **inputLayerName**
|
||||
Allows you to specify which layer to use for an input item.
|
||||
* **extraInputLayerName**
|
||||
Allows you to specify which layer to use for the extra input item.
|
||||
* **minPercentile** value between 0.0 - 1.0
|
||||
Allows you to specify the minimum percentile value to 'filter' lower bound input data
|
||||
* **maxPercentile** value between 0.0 - 1.0
|
||||
Allows you to specify the maximum percentile value to 'filter' upperbound bound input data
|
||||
* **plantingDate** if relevant
|
||||
Allows you to specify the date the crop is planted.
|
||||
* **measurementDate** if relevant
|
||||
allows you to specify the date when the measurements were taken.
|
||||
|
||||
Default input layer name for herbicide is the agent inputType used (lutum, om).
|
||||
Default percentile values for herbicide are 0.0 and 1.0.
|
||||
Default dates are 'inherited' from the cropfield item passed to the task.
|
||||
|
||||
```javascript
|
||||
{
|
||||
"inputLayerName": "customLayerName",
|
||||
"extraInputLayerName": "customLayerName",
|
||||
"plantingDate": "2020-02-01T00:00:00.000Z",
|
||||
"measurementDate": "2020-06-01T00:00:00.000Z",
|
||||
"minPercentile": "0.1",
|
||||
"maxPercentile": "0.95"
|
||||
}
|
||||
```
|
||||
|
||||
##### Create taskmap
|
||||
[Create Taskmap](Create-Taskmap.md)
|
||||
|
||||
##### Download the data
|
||||
In case the data is available it can be downloaded with the items API.
|
||||
> Request
|
||||
```javascript
|
||||
GET /api/v1/items/{itemcode}/download
|
||||
|
|
|
|||
Loading…
Reference in New Issue