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

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