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

Update 'VRAHerbicide-API.md'

Browse Source 
Improved herbicide documentation with latest changes
This commit is contained in:
Mark van der Wal 2020-06-10 12:38:50 +00:00
parent 5b72805644
commit 17498e26cf
1 changed files with 204 additions and 173 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

377
VRAHerbicide-API.md
View File

@ -1,173 +1,204 @@
## VRAHerbicide API ## VRAHerbicide API
[<< Home](README.md) [<< Home](README.md)
FarmMaps is an asynchronous architecture, the API flow keeps this in mind. 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). 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 For the currently available public FarmMaps API you can take a look at swagger: http://farmmaps.awtest.nl/swagger/index.html
**Input preperation** **Input preperation**
* Users can upload their own data if needed. (in case of when FarmMaps has not processed the required data). * 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. * The farmmaps file API can be used for this.
**Users can poll the task api to see if a task is completed** **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.** **This can be achieved with the task execution id obtained from calling the 'ItemTask' API.**
[Poll task status](Polling-task-status.md) [Poll task status](Polling-task-status.md)
**Users can query the API for child items of a cropfield to see what items it has.** **Users can query the API for child items of a cropfield to see what items it has.**
### API flow ### API flow
* Authenticate User * Authenticate User
* Optional steps * Optional steps
* *Create cropfield through FarmMaps API* * *Create cropfield through FarmMaps API*
* Item 'vnd.farmmaps.itemtype.cropfield' must be created with its data as specified in the 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. * 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. * This is an asynchronous process and can take a while before all data is collected in FarmMaps.
* *Upload own data* * *Upload own data*
* IF shape data, convert to geotiff. * IF shape data, convert to geotiff.
* Querying predefined herbicide agents (for input constants if none available beforehand) * 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.vraherbicide' must be executed to create an application map.
* Task 'vnd.farmmaps.task.taskmap' can be executed to create a taskmap. * Task 'vnd.farmmaps.task.taskmap' can be executed to create a taskmap.
* Download item data (tiff of shape) * Download item data (tiff of shape)
### Steps ### Steps
[Authentication](Authentication.md) [Authentication](Authentication.md)
##### Optional ##### Optional
[Create Cropfield](Create-Cropfield.md) [Create Cropfield](Create-Cropfield.md)
[Upload Data](Upload-Data.md) [Upload Data](Upload-Data.md)
###### Transform shape to geotiff ###### Transform shape to geotiff
The VRAHerbicide task only processes tiff items as input. 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'. 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. 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. This new geotiff item should be used as input to the a task.
> Request > Request
```javascript ```javascript
POST /api/v1/items/{code}/tasks POST /api/v1/items/{code}/tasks
{ {
"taskType": "vnd.farmmaps.task.shapetogeotiff" "taskType": "vnd.farmmaps.task.shapetogeotiff"
} }
``` ```
> Response 201 > Response 201
```javascript ```javascript
{ {
"code": "string", "code": "string",
"taskType": "vnd.farmmaps.task.shapetogeotiff" "taskType": "vnd.farmmaps.task.shapetogeotiff"
} }
``` ```
Response 400 Tasktype not found Response 400 Tasktype not found
Response 401 Not authenticated Response 401 Not authenticated
Response 403 No WRITE permissions in item Response 403 No WRITE permissions in item
Response 404 Item not found Response 404 Item not found
###### Querying predefined herbicide agents. ###### 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. 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 > Request
```javascript ```javascript
GET /api/v1/items/?it=vnd.farmmaps.package.vra.herbicide GET /api/v1/items/?it=vnd.farmmaps.package.vra.herbicide
``` ```
> Response 201 > Response 201
```javascript ```javascript
{ {
"code": "....", "code": "....",
"data": { "data": {
"agents": [ "agents": [
{ {
"name": "Liberator", "name": "Liberator",
"SoilType": "Dalgrond", "SoilType": "Dalgrond",
"ExtraInputType": "Lutum", "ExtraInputType": "Lutum",
"MinDosis": 2, "MinDosis": 2,
"MaxDosis": 3, "MaxDosis": 3,
"A": 0.1428, "A": 0.1428,
"B": 1.285714, "B": 1.285714,
"C": 1, "C": 1,
"D": 97, "D": 97,
"E": 3, "E": 3,
"P": 1, "P": 1,
"Crop": "Zetmeelaardappelen" "Crop": "Zetmeelaardappelen"
} }
] ]
} }
} }
``` ```
Response 400 Itemtype not found Response 400 Itemtype not found
Response 401 Not authenticated Response 401 Not authenticated
Response 403 No READ permissions in item Response 403 No READ permissions in item
Response 404 Items not found Response 404 Items not found
###### Creating an application map with the VRAHerbicide task ###### Creating an application map with the VRAHerbicide task
Execute the task with the item code of the cropfield as parameter inside {code}. 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. 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. {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. 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. 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). The resulting application map will be created as a child item of the cropfield item (this can be queried).
> Request > Request
```javascript ```javascript
POST /api/v1/items/{code}/tasks POST /api/v1/items/{code}/tasks
{ {
"taskType": "vnd.farmmaps.task.vraherbicide", "taskType": "vnd.farmmaps.task.vraherbicide",
"attributes": { "attributes": {
"inputCode": "{itemCode}", "inputCode": "{itemCode}",
"extraInputCode": "{extraItemCode}", "extraInputCode": "{extraItemCode}",
"agent": { "agent": {
"SoilType": "Dalgrond", "SoilType": "Dalgrond",
"ExtraInputType": "Lutum", "ExtraInputType": "Lutum",
"MinDosis": 2, "MinDosis": 2,
"MaxDosis": 3, "MaxDosis": 3,
"A": 0.1428, "A": 0.1428,
"B": 1.285714, "B": 1.285714,
"C": 1, "C": 1,
"D": 97, "D": 97,
"E": 3, "E": 3,
"P": 1, "P": 1,
"Crop": "Zetmeelaardappelen" "Crop": "Zetmeelaardappelen"
} }
} }
} }
``` ```
> Response 201 > Response 201
```javascript ```javascript
{ {
"code": "string", // code of task operation, can be queried for status "code": "string", // code of task operation, can be queried for status
"taskType": "vnd.farmmaps.task.vraherbicide", "taskType": "vnd.farmmaps.task.vraherbicide",
"attributes": { "attributes": {
"inputCode": "{itemCode}", "inputCode": "{itemCode}",
"extraInputCode": "{extraItemCode}", "extraInputCode": "{extraItemCode}",
"agent": { "agent": {
"SoilType": "Dalgrond", "SoilType": "Dalgrond",
"ExtraInputType": "Lutum", "ExtraInputType": "Lutum",
"MinDosis": 2, "MinDosis": 2,
"MaxDosis": 3, "MaxDosis": 3,
"A": 0.1428, "A": 0.1428,
"B": 1.285714, "B": 1.285714,
"C": 1, "C": 1,
"D": 97, "D": 97,
"E": 3, "E": 3,
"P": 1, "P": 1,
"Crop": "Zetmeelaardappelen" "Crop": "Zetmeelaardappelen"
} }
} }
} }
``` ```
Response 400 Tasktype not found Response 400 Tasktype not found
Response 401 Not authenticated Response 401 Not authenticated
Response 403 No WRITE permissions in item Response 403 No WRITE permissions in item
Response 404 Item not found Response 404 Item not found
##### Create taskmap ##### Optional input parameters #####
[Create Taskmap](Create-Taskmap.md) There are some optional task attribute input parameters for greater flexibility.
##### Download the data * **inputLayerName**
In case the data is available it can be downloaded with the items API. Allows you to specify which layer to use for an input item.
> Request * **extraInputLayerName**
```javascript Allows you to specify which layer to use for the extra input item.
GET /api/v1/items/{itemcode}/download * **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