Documentatie/VRAPoten-API.md

## VRAPoten API v0.1.1
[<< Home](README.md)  

FarmMaps is an asynchronous architecture, the API flow keeps this in mind.
The API 2 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.**  
[Poll task status](Polling-task-status.md)  

### 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 
[Authentication](Authentication.md)

###### Create cropfield with FarmMaps API (optional)
[Create Cropfield](Create-Cropfield.md)

###### Uploading own data (optional)
[Upload Data](Upload-Data.md)

###### Creating appliance maps
Execute the VRAPotenTask with the item code of the cropfield as parameter inside {code}.  
Use the input map code inside {itemCode}, specifying an inputCode is optional.  
In case of no specified inputCode the BOFEK data is looked up and if it could not be found the task gives an error.

> 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  


##### Optional input parameters #####
There are some optional task attribute input parameters for greater flexibility.

* **countPerArea**  
 * "countPerArea" Allows you to specify if spacing in cm needs to be calculated to count per area in m2.
 * "useShadow" Use shadow map if available.

defaults are false

```javascript
{
    "countPerArea": true,
    "useShadow": true
}
```

###### 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