Merge branch 'master' of https://git.akkerweb.nl/FarmMaps/Documentatie.wiki

2020-04-07 13:29:53 +02:00 · 2020-04-07 13:29:53 +02:00 · 5067fce553
commit 5067fce553
parent a90a8c4e91 fc84c89dd7
6 changed files with 83 additions and 9 deletions
--- a/Authentication.md
+++ b/Authentication.md
@ -1,10 +1,11 @@
 ## Autentication
-Farmmaps uses OpenID: https://auth0.com/docs/protocols/oidc/openid-connect-discovery  
+Farmmaps uses OpenID-connect: https://openid.net/connect/

 It is recommended to use a library to facilitate the authentication.  
 To get the openid configuration call the following url: https://accounts.farmmaps.awtest.nl/.well-known/openid-configuration 

 The user could also use the openid-configuration to handle authentication by themselves.  
+https://identitymodel.readthedocs.io/en/latest/native/overview.html

 The token received needs to be used in the request header.
 >'Authorization': 'bearer {token}'
--- a/Create-Cropfield.md
+++ b/Create-Cropfield.md
@ -25,7 +25,7 @@ GET /api/v1/folders/my_drive
 * Create a 'FOLDER' item as a child of the 'my_drive' item.  
 >Request
 ```javascript
-POST /api/v1/item
+POST /api/v1/items
 {
  "parentCode": "{my_drive_code}",
  "itemType": "FOLDER",
@ -64,15 +64,19 @@ Response 401 Not authenticated
 Response 403 No WRITE permissions in parent item  
 Response 404 Parent Item not found  

-* Create a 'vnd.farmmaps.itemtype.cropfield' item as a child of the 'FOLDER' item.
+* Create a 'vnd.farmmaps.itemtype.cropfield' item as a child of the 'FOLDER' item.  
+Needs to contain dataDate and dataEndDate to specify cropfield season.  
+dataDate needs to be before dataEndDate and cannot be the same day.  
+ 
 > Request
 ```javascript
-POST /api/v1/item
+POST /api/v1/items
 {
    "parentCode": "{FOLDER_item_code}",
    "itemType": "vnd.farmmaps.itemtype.cropfield",
    "name": "cropfield for VRA",
-    "dataDate": "2019-11-25",
+    "dataDate": "2019-1-18T10:16:21.455Z",
+    "dataEndDate": "2019-12-18T10:16:21.455Z",
    "data": {},
    "geometry": {"type":"Polygon","coordinates":[[[6.09942873984307,53.070025028087],[6.09992507404607,53.0705617890585],[6.10036959220086,53.0710679529031],[6.10065149010421,53.0714062774307],[6.10087493644271,53.0716712354474],[6.10091082982487,53.0716936039203],[6.10165087441291,53.0712041549161],[6.10204994718318,53.0709349338005],[6.10263143118855,53.0705789370018],[6.10311578125011,53.0702657538294],[6.10331686552072,53.0701314102389],[6.103326530575,53.070119463569],[6.10309137950343,53.0699829669055],[6.10184241586523,53.0692902201371],[6.10168497998891,53.0691984306747],[6.10092987659869,53.0694894453514],[6.09942873984307,53.070025028087]]]}
 }
--- a/Polling-task-status.md
+++ b/Polling-task-status.md
@ -0,0 +1,55 @@
+## Polling task status
+
+When a task is executed with the task API your retrieve a code.  
+This code can be used to poll the status of an item task execution.  
+
+The response 'message' field can contain a string message based on the context.  
+
+#### Get a list task of status for a given item
+> Request
+```javascript
+GET /api/v1/items/{code}/tasks
+```
+
+> Response 200 OK
+```javascript
+[
+{
+  "taskType": "string",
+  "code": "string",
+  "message": "string",
+  "state": "Error, Ok, Scheduled, Processing",
+  "started": "2020-03-20T11:13:20.568Z",
+  "finished": "2020-03-20T11:13:20.568Z"
+},
+{
+  "taskType": "string",
+  "code": "string",
+  "state": "Error, Ok, Scheduled, Processing",
+}
+]
+```  
+Response 401 Not authenticated  
+Response 403 No READ permissions in parent item  
+Response 404 Parent Item not found 
+
+#### Get the status of a task for a given item and item task code
+> Request
+```javascript
+GET /api/v1/items/{code}/tasks/{itemTaskCode}
+```
+
+> Response 200 OK
+```javascript
+{
+  "taskType": "string",
+  "code": "string",
+  "message": "string",
+  "state": "Error, Ok, Scheduled, Processing",
+  "started": "2020-03-20T11:13:20.568Z",
+  "finished": "2020-03-20T11:13:20.568Z"
+}
+```  
+Response 401 Not authenticated  
+Response 403 No READ permissions in parent item  
+Response 404 Parent Item not found 
--- a/Upload-Data.md
+++ b/Upload-Data.md
@ -2,6 +2,10 @@
 If the user wants to upload custom data (lutum/ec) they can use the FarmMaps file API.  
 The API is based on the google drive API.  

+C# explanation:   
+https://developers.google.com/api-client-library/dotnet/guide/media_upload  
+https://developers.google.com/drive/api/v3/manage-uploads#resumable
+
 * Start request

 > Request
--- a/VRANbs-API.md
+++ b/VRANbs-API.md
@ -12,12 +12,14 @@ For the currently available public FarmMaps API you can take a look at swagger:
    * But API users can delete their own items through the farmmaps API.

 **Input preperation**
-* Users can upload their own soilmaps 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.

 **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.**  
-**Users can query the API for child items of a cropfield to see what data it has.**
+[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
@ -26,7 +28,7 @@ For the currently available public FarmMaps API you can take a look at swagger:
        * 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*
+    * *Upload own data*
        * IF shape data, convert to geotiff.
    * *Create 'vnd.farmmaps.itemtype.user.input' item for targetn calculation.*
        * *Task 'vnd.farmmaps.task.vranbs' can be executed with the 'targetn' operation*
@ -140,6 +142,7 @@ Response 404 Parent Item not found


 **Call the vranbs task**  
+Execute the VRANbsTask with the item code of the cropfield as parameter inside {code}. 
 Use the code obtained from creating the user.input item as a parameter in {itemCode}.  
 > Request
 ```javascript
@ -149,6 +152,8 @@ POST /api/v1/items/{code}/tasks
  "attributes": {
      "operation": "targetn",
    "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"
@ -217,6 +222,8 @@ POST /api/v1/items/{code}/tasks
  "attributes": {
      "operation": "uptake",
      "inputCode": "{itemCode}",
+      "plantingDate": "2020-02-01T00:00:00.000Z",
+      "measurementDate": "2020-06-01T00:00:00.000Z",
      "inputType": "irmi", // yara, ci, irmi or wdvi
  }
 }
@ -253,6 +260,8 @@ POST /api/v1/items/{code}/tasks
  "attributes": {
      "operation": "nitrogen",
      "inputCode": "{itemCode}",
+      "plantingDate": "2020-02-01T00:00:00.000Z",
+      "measurementDate": "2020-06-01T00:00:00.000Z",
      "inputType": "irmi", // yara, ci, irmi or wdvi
      "targetN": "249.22948"
  }
--- a/VRAPoten-API.md
+++ b/VRAPoten-API.md
@ -12,8 +12,9 @@ For the currently available public FarmMaps API you can take a look at swagger:
 * 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**
+**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)  

 ### API flow
 * Authenticate User