Update page 'VRAPoten API'

2020-01-20 13:44:34 +00:00
commit 4961dd1ad9
1 changed files with 357 additions and 0 deletions
--- a/VRAPoten-API.md
+++ b/VRAPoten-API.md
@@ -0,0 +1,357 @@
+## API v0.1
+[<< 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.
+
+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.**  
+
+### 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 
+Farmmaps uses OpenID: https://auth0.com/docs/protocols/oidc/openid-connect-discovery  
+
+It is recommended to use a library to facilitate the authentication.  
+To get the openid configuration call the following url: http://accounts.awtest.nl/.well-known/openid-configuration  
+
+The user could also use the openid-configuration to handle authentication by themselves.  
+
+The token received needs to be used in the request header.
+>'Authorization': 'bearer {token}'
+
+The token can also easily be created through the swagger documentation:  
+https://farmmaps.awtest.nl/swagger/index.html 
+
+###### Create cropfield with FarmMaps API (optioneel)
+If there aren't any relevant cropfields in FarmMaps for the creation of VRAPoten appliance maps, you can create them yourself by executing the following steps:  
+* Execute the following REST call to create the 'my_drive' item which contains the needed itemcode:  
+> Request
+```
+GET /api/v1/folders/my_drive
+```  
+> Response 200 Succes
+```javascript
+{
+  "url": "string",
+  "code": "string",
+  "name": "string",
+  "created": "2019-12-18T09:49:35.741Z",
+  "updated": "2019-12-18T09:49:35.741Z",
+  "dataDate": "2019-12-18T09:49:35.741Z",
+  "itemType": "string",
+  "sourceTask": "string",
+  "size": 0,
+  "state": 0,
+  "thumbnail": true
+}
+```
+
+* Create a 'FOLDER' item as a child of the 'my_drive' item.  
+>Request
+```javascript
+POST /api/v1/item
+{
+  "parentCode": "{my_drive_code}",
+  "itemType": "FOLDER",
+  "name": "string",
+  "data": {},
+  "dataDate": "2019-12-18T09:59:18.893Z",
+  "geometry": {},
+  "tags": [
+    "string"
+  ]
+}
+```
+> Response 201 Created
+```javascript
+{
+  "parentCode": "string",
+  "geometry": {},
+  "data": {},
+  "tags": [
+    "string"
+  ],
+  "url": "string",
+  "code": "string",
+  "name": "string",
+  "created": "2019-12-18T10:16:21.455Z",
+  "updated": "2019-12-18T10:16:21.455Z",
+  "dataDate": "2019-12-18T10:16:21.455Z",
+  "itemType": "string",
+  "sourceTask": "string",
+  "size": 0,
+  "state": 0,
+  "thumbnail": true
+}
+```  
+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.
+> Request
+```javascript
+POST /api/v1/item
+{
+    "parentCode": "{FOLDER_item_code}",
+    "itemType": "vnd.farmmaps.itemtype.cropfield",
+    "name": "cropfield for VRA",
+    "dataDate": "2019-11-25",
+    "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]]]}
+}
+```  
+> Response 201 Created
+```Javascript
+{
+  "parentCode": "string",
+  "geometry": {},
+  "data": {},
+  "tags": [
+    "string"
+  ],
+  "url": "string",
+  "code": "string",
+  "name": "string",
+  "created": "2019-12-18T10:16:21.455Z",
+  "updated": "2019-12-18T10:16:21.455Z",
+  "dataDate": "2019-12-18T10:16:21.455Z",
+  "itemType": "string",
+  "sourceTask": "string",
+  "size": 0,
+  "state": 0,
+  "thumbnail": true
+}
+```
+
+* Execute the workflow task with the cropfield item code.  
+This steps makes sure that FarmMaps aggregates all needed data for the cropfield.  
+> Request
+```javascript
+POST /api/v1/items/{code}/tasks
+{
+   "taskType": "vnd.farmmaps.task.workflow"
+}
+```  
+> 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  
+
+###### Uploading own data (optioneel)
+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.  
+
+* Start request
+
+> Request
+```javascript
+POST https://farmmaps.awacc.nl/api/v1/file
+
+Host: farmmaps.awtest.nl
+Authorization: Bearer < Token >
+X-Upload-Content-Length: 13507747
+X-Upload-Content-Type: application/x-zip-compressed
+Content-Type: application/json; charset=UTF-8
+Content-Length: 181
+
+{ 
+   "name":"Grondsoorten2006-SHP.zip",
+   "mimeType":"application/x-zip-compressed",
+   "size":13507747,
+   "lastModified":1575293019617,
+   "parentCode":"c0787987a3f7449c97eecd6d015eb4c2:USER_FILES"
+}
+```  
+> Response
+```javascript
+Location: /api/v1/file/2831cd05ddc0415784930059c658db55
+Content-Length: 194
+Content-Type: application/json; charset=utf-8
+
+{
+   "code":"2831cd05ddc0415784930059c658db55",
+   "chunks":1,
+   "parentCode":"c0787987a3f7449c97eecd6d015eb4c2:USER_FILES",
+   "name":"Grondsoorten2006-SHP.zip",
+   "size":13507747,
+   "chunkSize":13507747,
+   "data":{}
+}
+```  
+
+* Request upload chunk 1  
+
+> Request
+```javascript
+PUT https://farmmaps.awtest.nl/api/v1/file/2831cd05ddc0415784930059c658db55 
+
+Host: farmmaps.awtest.nl
+Authorization: Bearer < Token >
+Content-Type: application/octet-stream
+Content-Length: 2097152
+Content-Range: bytes 0-2097151/13507747
+
+<data>
+```
+> Response
+```javascript
+HTTP/1.1 308 Resume Incomplete
+
+Range: 0-2097151
+Content-Length: 17
+
+Resume Incomplete
+```
+
+* Request upload chunk 2  
+
+> Request
+```javascript
+PUT https://farmmaps.awtest.nl/api/v1/file/2831cd05ddc0415784930059c658db55
+
+Host: farmmaps.awtest.nl
+Authorization: Bearer < Token >
+Content-Type: application/octet-stream
+Content-Length: 2097152
+Content-Range: bytes 2097152-4194303/13507747
+
+<data>
+```
+> Response
+```javascript
+HTTP/1.1 308 Resume Incomplete
+
+Range: 0-4194303
+Content-Length: 17
+
+Resume Incomplete
+```
+
+* Final request  
+
+> Request
+```javascript
+PUT https://farmmaps.awtest.nl/api/v1/file/2831cd05ddc0415784930059c658db55
+
+Host: farmmaps.awtest.nl
+Authorization: Bearer < Token >
+Content-Type: application/octet-stream
+Content-Length: 924835
+Content-Range: bytes 12582912-13507746/13507747
+
+<data>
+```
+> Response
+```javascript
+Upload response laatste chunk
+
+HTTP/1.1 201 Created
+
+Range: 0-13507746
+Content-Length: 0
+```
+
+###### Creating appliance maps
+Execute the VRAPotenTask with the item code of the cropfield as parameter inside {code}.
+Use the input map code inside {itemCode}.
+
+> 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  
+
+###### Create taskmap
+The user can use the "ItemTask" API to execute the TaskmapTask with the item code from the appliancemap in {code}.  
+
+> Request
+```javascript
+POST /api/v1/items/{code}/tasks
+{  
+  "taskType": "vnd.farmmaps.task.taskmap"  
+}
+```  
+> 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  
+
+###### Data downloaden
+In case the data is available in can be downloaded with the File API.
+> Request
+```javascript
+GET /api/v1/items/{itemcode}/data
+```