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

Create-b-cropfield.md

@@ -0,0 +1,215 @@
+## Creating a cropfield
+This page explains what a cropfield is, and how to create one through the API.  
+
+Agricultural datasets generally refer to a specif crop, at a specific location at a specific time. 
+Therefore, we need to create a "Cropfield" item, to define this location and a timeframe our data relates to. 
+A cropfield provides a convienient way to group all data for a crop grown on a specific plot during a season.
+Farmmaps also uses the cropfield to collect and prepare context data such as weather, satelite imagery etc.
+
+To create a cropfield we:
+* Get the parent folder to place the cropfield under
+* Create a folder under this element (optional)
+* Create the cropfield
+
+**Prerequisites**  
+To create a cropfield we need:
+
+* an acces token
+* coordinates of the cropfield (what points define the plot contour)
+* a startdate and an end date (what timeframe does this data aply to)
+
+### Get parent element 
+First, we'll get the parent code needed to place the cropfield in the hierarchy.
+
+**Request**  
+Replace `<acces token>` with your actual token.
+```http
+GET https://farmmaps.awacc.nl/api/v1/folders/my_drive? HTTP/1.1
+Host: farmmaps.awacc.nl
+Accept: application/json
+Authorization: Bearer <access token>
+```
+
+**Response**  
+The response will be something similar to:
+
+```http
+HTTP/1.1 200 OK
+Server: nginx/1.14.0 (Ubuntu)
+Date: Tue, 21 Apr 2020 09:57:07 GMT
+Content-Type: application/json; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Cache-Control: no-store,no-cache
+Pragma: no-cache
+Content-Encoding: br
+Vary: Accept-Encoding
+
+{
+    "url":"/api/v1/folders/f25d8765a1cd407cb235961c73c268cf:USER_FILES",
+    "code":"f25d8765a1cd407cb235961c73c268cf:USER_FILES",
+    "name":"My Drive",
+    "created":"2019-09-25T19:39:33.841835",
+    "updated":"2019-09-25T19:39:33.841835",
+    "itemType":"ROOT_FOLDER",
+    "size":0,
+    "state":0,
+    "thumbnail":false
+}
+```
+So the `parentcode` we need is **"f25d8765a1cd407cb235961c73c268cf:USER_FILES"**  
+You can also find the code of a folder by browsing the folders in your FarmMaps account through the web interface.  
+The item code is the last part of the URL.
+
+### Create folder
+Depending on how you want to organise things, you might choose to make a separate folder for the cropfield. 
+A folder can be created by creating an item with itemType `FOLDER`. 
+
+> **Note:** At the moment, subfolders can not be created directly under the root folder, create a folder through the web interface first.
+
+**Request**
+```http
+POST /api/v1/items HTTP/1.1
+Accept: application/json
+Authorization: Bearer <access token>
+Content-Type: application/json
+Cache-Control: no-cache
+Host: farmmaps.awacc.nl
+Accept-Encoding: gzip, deflate, br
+Connection: keep-alive
+Content-Length: 210
+
+{
+  "parentCode": "f25d8765a1cd407cb235961c73c268cf:USER_FILES",
+  "itemType": "FOLDER",
+  "name": "My_new_folder",
+  "data": {},
+  "dataDate": "2020-04-24T09:59:18.893Z",
+  "geometry": {},
+  "tags": [ "string" ]
+}  
+```
+
+When the folder is created successfully we should recieve something like this:
+
+**Response**
+```http
+{
+  "parentCode": "string",
+  "geometry": {},
+  "data": {},
+  "tags": [
+    "string"
+  ],
+  "url": "string",
+  "code": "string",
+  "name": "My_new_folder",
+  "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
+}
+```
+
+### Create the cropfield
+Now we can create the cropfield. We do so by setting `"itemType": "vnd.farmmaps.itemtype.cropfield"` and adding data to the geometry parameter.
+Generally, a cropfield contour would be defined as a polygon, so we add `"type":"Polygon" and all the coordinates.  
+We also need to specify a `dataDate` and a `dataEndDate` to indicate the the timeframe of the growing season.  
+The `dataDate` needs to be before `dataEndDate` and cannot be on the same day.
+
+**Request**
+
+```http
+POST /api/v1/items HTTP/1.1
+Accept: application/json
+Authorization: Bearer <acces token>
+Content-Type: application/json
+Cache-Control: no-cache
+Host: farmmaps.awacc.nl
+Accept-Encoding: gzip, deflate, br
+Connection: keep-alive
+Content-Length: 916
+
+{
+    "parentCode": "6601a06d812b40f9830c9fe4e63b1944",
+    "itemType": "vnd.farmmaps.itemtype.cropfield",
+    "name": "cropfield for VRA",
+    "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]]]}
+}
+```
+
+**Response**
+When the cropfield is created, it should be visible through the FarmMaps web interface (under "My Drive" in the respective parent folder).
+We should have the following response:
+
+```http
+HTTP/1.1 201 Created
+Server: nginx/1.14.0 (Ubuntu)
+Date: Fri, 24 Apr 2020 08:56:45 GMT
+Content-Type: application/json; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Cache-Control: no-store,no-cache
+Pragma: no-cache
+Content-Encoding: br
+Location: /api/v1/items/8ecbaa2d85d5484db7f16b281b7cd013
+Vary: Accept-Encoding
+
+{
+    "parentCode":"6601a06d812b40f9830c9fe4e63b1944",
+    "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]]
+        ]},
+        "data":{},
+        "tags":[],
+        "isEditable":false,
+        "url":"/api/v1/items/8ecbaa2d85d5484db7f16b281b7cd013",
+        "code":"8ecbaa2d85d5484db7f16b281b7cd013",
+        "name":"cropfield for VRA",
+        "created":"2020-04-24T08:56:45.3727807Z",
+        "updated":"2020-04-24T08:56:45.3727807Z",
+        "dataDate":"2019-01-18T10:16:21.455Z",
+        "itemType":"vnd.farmmaps.itemtype.cropfield",
+        "size":0,
+        "state":0,
+        "thumbnail":false
+      }
+```
+
+**Troubleshooting**
+|Status code|Description|
+|---|---|
+|201|Cropfield created successfully|
+|401|Error: not authenticated|
+|403|Error: No write permissions in parent item|
+|404|Error: Parent item not found|
+
+Now that the cropfield has been created, we can start the processing by running a task.
+This will collext all context data for the cropfield. 
+We need the ItemCode of the cropfield to start the task so keep this at hand.
+