From 4961dd1ad93dd2d2d21ac3f3526752fca1b9942f Mon Sep 17 00:00:00 2001 From: Mark van der Wal Date: Mon, 20 Jan 2020 13:44:34 +0000 Subject: [PATCH] Update page 'VRAPoten API' --- VRAPoten-API.md | 357 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 357 insertions(+) create mode 100644 VRAPoten-API.md diff --git a/VRAPoten-API.md b/VRAPoten-API.md new file mode 100644 index 0000000..fecbea8 --- /dev/null +++ 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 + + +``` +> 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 + + +``` +> 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 + + +``` +> 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 +``` \ No newline at end of file