Flow of REST request between Emikat and CSIS

patrickkaleta commented 5 years ago

Overview

In this issue we will describe the flow of individual REST calls between Emikat and CSIS, how to access the endpoints on Drupal-side and what content(-fields) should be expected in each response.

General procedure

CSIS needs to trigger Emikat (send all necessary information and receive Emikat's internal ID of our Study) once a new Study is created and sufficient data has been added, so that Emikat can start the calculations. TODO: We need to define how much data is "sufficient" here: #6.
Emikat requests the data it needs from the Drupal REST endpoint (going to be either special views or the complete nodes exported as json or hal_json)
Emikat needs to trigger Drupal once results are available and Drupal needs to trigger Emikat once changes to the Study are made.

Individual REST endpoints

1) Initial Study information

Link: csis.myclimateservice.eu/rest/emikat/study/[StudyID] This link will be given to Emikat in the initial trigger event from the CSIS. BasicAuth is used as authentication. Emikat can use the "Emikat" user in the CSIS, which was created for this purpose. This endpoint uses the REST Group View and displays the following properties:

study_title: Name of the Study
study_description: Description of the Study
study_area_left: position of the left side of the bounding box
study_area_top: position of the top side of the bounding box
study_area_right: position of the right side of the bounding box
study_area_bottom: position of the bottom side of the bounding box
path_data_package: Link to the endpoint with additional information about the used data package
path_resources: Link to View endpoint showing all resources in that Study/datapackage

2) Data package information

Link: csis.myclimateservice.eu/node/[DatapackageID]?_format=hal_json This endpoint is currently not implemented as a view, so the complete data package is displayed. This can be changed if necessary, so that only relevant fields are displayed.

3) Resources information

Link: csis.myclimateservice.eu/rest/emikat/dp[DatapackageID]/resources This endpoint uses the REST Node View and displays the following properties:

resource_description: Description of resource (plain text)
resource_format: format of resource (Geojson, jpeg, Shapefile, ...)
resource_url: array of URLs to external source(s) of resource

additional REST endpoints ???

patrickkaleta commented 5 years ago

@humerh since we don't have the initial trigger yet and there is only one study available, you can test this by using this URL: https://csis.myclimateservice.eu/rest/emikat/study/1

If you need additional fields (or would like to rename some of the fields or use different formats e.g. for the study_area) in one of the endpoints or complete new endpoints, please write them as comments here in this issue.

patrickkaleta commented 5 years ago

@humerh as was just discussed I changed the study_area field in the response body, so that it now shows to coordinates for left, top, right and bottom. For that I had to split the original field into 4 new fields.

humerh commented 5 years ago

@patrickkaleta additionally I need the list of ressources in the data package. For each ressource I need at least following fields:

description
format
url

patrickkaleta commented 5 years ago

@patrickkaleta additionally I need the list of ressources in the data package. For each ressource I need at least following fields:

description

format

url

I created a new REST endpoint (accessible by the Emikat-user in the CSIS) at the following URL-pattern: .../rest/emikat/dp/[DatapackageID]/resources @humerh That link is now included in the "Initial Study information" endpoint (described on top in the first comment), so Emikat should have no trouble getting to it.

maesbri commented 5 years ago

@humerh be aware that in the data package resources, the "path" property can be either a url or an array of urls

patrickkaleta commented 5 years ago

@humerh be aware that in the data package resources, the "path" property can be either a url or an array of urls

Interesting! In that case I believe that the path field in Drupal should be allowed to contain unlimited values and not just one. @fgeyer16 since we already have data in that field, can we change the settings from "limited to 1" to "unlimited" without running into problems?

fgeyer16 commented 5 years ago

@fgeyer16 since we already have data in that field, can we change the settings from "limited to 1" to "unlimited" without running into problems?

As far as I experienced making a single value field to a multi value works and does not cause problems. Only the other direction does not work

patrickkaleta commented 5 years ago

@fgeyer16 since we already have data in that field, can we change the settings from "limited to 1" to "unlimited" without running into problems?

As far as I experienced making a single value field to a multi value works and does not cause problems. Only the other direction does not work

That was also my believe. I tested changing the field's cardinality locally and it worked without problems. I will now apply this in the CSIS.

patrickkaleta commented 5 years ago

Closing this, since basic communication between Emikat and Drupal is already implemented by now and working. For reference purposes I'll keep this issue pinned to the top.

clarity-h2020 / emikat