diff --git a/Home.md b/Home.md index 8740e8d..988b294 100644 --- a/Home.md +++ b/Home.md @@ -61,3 +61,4 @@ To continue please see one of the articles below: ### Use-case examples * [VRAPoten-API](/wiki/VRAPoten-API) * [VRANbs-API](/wiki/VRANbs-API) +* [VRAHerbicide-API](/wiki/VRAHerbicide-API) diff --git a/VRAHerbicide-API.md b/VRAHerbicide-API.md new file mode 100644 index 0000000..55687e6 --- /dev/null +++ b/VRAHerbicide-API.md @@ -0,0 +1,172 @@ +## VRAHerbicide API +[<< 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 (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](https://git.akkerweb.nl/FarmMaps/Documentatie/wiki/Polling-task-status) + +**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' 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 data* + * IF shape data, convert to geotiff. +* 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](https://git.akkerweb.nl/FarmMaps/Documentatie/wiki/Authentication) + +##### Optional +[Create Cropfield](https://git.akkerweb.nl/FarmMaps/Documentatie/wiki/Create-Cropfield) +[Upload Data](https://git.akkerweb.nl/FarmMaps/Documentatie/wiki/Upload-Data) + +###### 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 Tasktype 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](https://git.akkerweb.nl/FarmMaps/Documentatie/wiki/Create-Taskmap) + +##### Download the data +In case the data is available it can be downloaded with the File API. +> Request +```javascript +GET /api/v1/items/{itemcode}/data \ No newline at end of file diff --git a/VRANbs-API.md b/VRANbs-API.md index 3ebf191..fa4c2d8 100644 --- a/VRANbs-API.md +++ b/VRANbs-API.md @@ -154,7 +154,6 @@ POST /api/v1/items/{code}/tasks "inputCode": "{itemCode}", "plantingDate": "2020-02-01T00:00:00.000Z", "measurementDate": "2020-06-01T00:00:00.000Z", - "inputType": "irmi", // yara, ci, irmi or wdvi "purposeType": "consumption", // consumption, fries, potato, starch "targetYield": "60" }