Documentatie/VRAHaulmkilling-API.md

## VRAHaulmkilling 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: https://test.farmmaps.eu/swagger  

**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 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 haulmkilling agents (to use as input for the task).
* Task 'vnd.farmmaps.task.vrahaulmkilling' 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 VRAHaulmkilling 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 a sibling of the shape item with the same parent
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 haulmkilling agents.
A list of haulmkilling agents can be requested by getting the "vnd.farmmaps.package.vra.haulmkilling" item and reading it's data field 'agents' array content.  
> Request
```javascript
GET /api/v1/items/?it=vnd.farmmaps.package.vra.haulmkilling
```
> Response 201
```javascript
{   
    "code": "....",
    // ....
    "data": 
    {
        "agents": [
        {
                "name": "spotlightplus",
                "values": {
                    "ndvi": [
                        {
                            "max": 0.95,
                            "min": 0.3,
                            "fexp": 1.35,
                            "fmul": 0.3,
                            "option": "risk.standard"
                        },
                        {
                            "max": 0.9,
                            "min": 0.25,
                            "fexp": 1.39,
                            "fmul": 0.25,
                            "option": "risk.low"
                        },
                        {
                            "max": 1,
                            "min": 0.35,
                            "fexp": 1.3,
                            "fmul": 0.36,
                            "option": "risk.high"
                        }
                    ],
                    "wdvi": [
                        {
                            "max": 0.95,
                            "min": 0.3,
                            "fexp": 2.97,
                            "fmul": 0.3,
                            "option": "risk.standard"
                        },
                        {
                            "max": 0.9,
                            "min": 0.25,
                            "fexp": 2.97,
                            "fmul": 0.25,
                            "option": "risk.low"
                        },
                        {
                            "max": 1,
                            "min": 0.35,
                            "fexp": 2.97,
                            "fmul": 0.36,
                            "option": "risk.high"
                        }
                    ]
                },
                "supportedOptions": [
                    "risk.standard",
                    "risk.low",
                    "risk.high"
                ]
            }
        ],
        "validOptions": [
            "risk.standard",
            "risk.low",
            "risk.high",
            "weed",
            "split.first",
            "split.second"
        ]
    }
}
```

Response 400 Itemtype not found  
Response 401 Not authenticated  
Response 403 No READ permissions in item  
Response 404 Items not found  

The data structure contains the haulmkilling **agents** and the **valid options** available in farmmaps.  
Each agent contains a list of supported options and a key value map of a list of constants.  
The key is a supported inputtype (wdvi, ndvi) and the value is a list of constant objects like so:  
```javascript
{
    "name": "agentName",
    "values": {
        "ndvi": [
            {
                "max": 0.9,
                "min": 0.25,
                "fexp": 2.97,
                "fmul": 0.25,
                "option": "risk.low"
            },
            {
                "max": 0.95,
                "min": 0.3,
                "fexp": 1.35,
                "fmul": 0.3,
                "option": "risk.standard"
            }
            ],
        "wdvi": [{...}]
    }
}
```  
Each constant value object has an **'option'** associated with it that should also be within the **'validOptions'** list of the data structure.
 
###### Creating an application map with the VRAHaulmkilling task
Execute the task with the item code of the cropfield as parameter inside {code}.  
Use the code of the input item inside {itemCode}, this specifies an item to use as input.  

The resulting application map will be created as a child item of the cropfield item (this item can be queried).    
> Request
```javascript
POST /api/v1/items/{code}/tasks
{
  "taskType": "vnd.farmmaps.task.vrahaulmkilling",
  "attributes": {
      "inputCode": "{itemCode}",
      "inputType": "wdvi",
      "agentName": "reglone",
      "selectedOption": "risk.standard"
  }
}
```  
> Response 201
```javascript
{
  "code": "string", // code of task operation, can be queried for status
  "taskType": "vnd.farmmaps.task.vrahaulmkilling",
  "attributes": {
      "inputCode": "{itemCode}",
      "inputType": "wdvi",
      "agentName": "reglone",
      "selectedOption": "risk.standard"
  }
}
```

Response 400 Tasktype not found  
Response 401 Not authenticated  
Response 403 No WRITE permissions in item  
Response 404 Item not found  

**'inputCode'** needs to have a value that is gotten from the haulmkilling agent query.  
**'agentName'** needs to have a value that is gotten from the haulmkilling agent query.  
**'inputType'** needs to have a value that is gotten from the haulmkilling agent query.  
**'selectedOption'** needs to have a value that is gotten from the haulmkilling agent query.  

The given agent values(agentName, inputType and selectedOption) as specified above form a unique combination specifying correct agent data.  
For example, the agent with **'agentName'** needs to have an entry of **'inputType'** with a constant object with the **"option"** key and value **'selectedOption'**.  
```javascript
{
    "name": "<agentName>",
    "values": {
        "<inputType>": [
            {
                "max": 0.9,
                "min": 0.25,
                "fexp": 2.97,
                "fmul": 0.25,
                "option": "<selectedOption>"
            }
            ]
    }
}
```  

##### 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.
* **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 Haulmkilling is the agent inputType used (wdvi, ndvi).  
Default percentile values for Haulmkilling are 0.05 and 0.90.  
Default dates are 'inherited' from the cropfield item passed to the task.  

```javascript
{
    "inputLayerName": "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