Difference between revisions of "GRSF-services"

From Gcube Wiki
Jump to: navigation, search
(Service input)
(grsf-services-updater)
 
(19 intermediate revisions by the same user not shown)
Line 3: Line 3:
 
In this page we describe the components that are responsible for interacting with the gCube infrastructure for performing various activities about [https://support.d4science.org/projects/stocksandfisherieskb/wiki/GRSF GRSF] records. GRSF records are handled as dataset resources and are stored in the [https://i-marine.d4science.org/group/grsf/data-catalogue data catalogue]. The following image depicts a high level view of the architecture of components that are exploited for constructing the GRSF KB, publishing GRSF records and updating them. In the sequel we will focus and describe the components '''grsf-services-core''' and '''grsf-services-updater'''.
 
In this page we describe the components that are responsible for interacting with the gCube infrastructure for performing various activities about [https://support.d4science.org/projects/stocksandfisherieskb/wiki/GRSF GRSF] records. GRSF records are handled as dataset resources and are stored in the [https://i-marine.d4science.org/group/grsf/data-catalogue data catalogue]. The following image depicts a high level view of the architecture of components that are exploited for constructing the GRSF KB, publishing GRSF records and updating them. In the sequel we will focus and describe the components '''grsf-services-core''' and '''grsf-services-updater'''.
  
[[File:GRSF-components.png]]
+
[[File:GRSF components.jpg]]
  
 
== grsf-services-core ==
 
== grsf-services-core ==
Line 13: Line 13:
 
# The grsf-services-core component publishes the transformed JSON objects and retrieves the results.  
 
# The grsf-services-core component publishes the transformed JSON objects and retrieves the results.  
  
[[File:GRSF-records-publishing.png]]
+
[[File:GRSF records publishing.jpg]]
  
 
The component is being delivered as a software library. It is being triggered from MatWare after the construction of the GRSF KB.
 
The component is being delivered as a software library. It is being triggered from MatWare after the construction of the GRSF KB.
Line 19: Line 19:
 
== grsf-services-updater ==
 
== grsf-services-updater ==
  
This component is responsible for updating the status of a record, when the users requires so. More specifically the component is delivered as a service, that accepts incoming requests containing the record that will be updated, with its accompanying information (the new status, a narrative text describing the status update). Once a request has been received the service will update the contents in the GRSF KB, and return a response message information the caller for the results. The communication messages for the service are formulated JSON objects. The steps that are followed are described in detail below (with the corresponding part of the sequence diagram).
+
This component is responsible for updating the status of a record, when the users requires so. More specifically the component is delivered as a service, that accepts incoming requests containing the record that will be updated, with its accompanying information (the new status, a narrative text describing the status update). Once a request has been received the service will update the contents in the GRSF KB, and return a response message information the caller for the results. The communication messages for the service are formulated JSON objects. The service allows updating the following fields of a record:
  
# a new incoming request for a record status update is being received from the grsf-services-updater.  
+
* Updates the status of a record (available statuses: pending, approved, rejected, hidden, archived).
# grsf-services-updater validates that the request contains valid data
+
* Updates the short name of a record.
# grsf-services-updater updates the corresponding component in the GRSF KB. For this reason the appropriate SPARQL update query is being formulated and submitted to GRSF KB
+
* Updates the tracability flag of a record.
# grsf-services-updater returns a response (as a JSON object) with the result of the update process.
+
* Updates the list of connected exploiting resources.
 +
* Defines alternative merging operations with similar records.
  
[[File:GRSF-records-updating.png]]
+
[[File:GRSF records updating.jpg]]
  
 
=== Check service availability ===  
 
=== Check service availability ===  
Line 37: Line 38:
 
This will show a landing page with instructions for using the service indicating that the service is up and running.  
 
This will show a landing page with instructions for using the service indicating that the service is up and running.  
  
=== Service input ===  
+
=== Service endpoints ===
  
 +
The service exposes the following endpoints:
 +
 +
* updater: allows updating a record.
 +
* revert: allows reverting the proposed merging of records.
 +
* info: shows detailed information about the services (triplestore and publisher information).
 +
 +
==== Updater endpoint ====
 +
 +
It is a POST service that allows updating various infomation about a record.
 +
 +
===== Service Request =====
 
The service accepts as input JSON objects. Some of the fields in the object are mandatory while others are optional. The following table lists the fields of the JSON objects.  
 
The service accepts as input JSON objects. Some of the fields in the object are mandatory while others are optional. The following table lists the fields of the JSON objects.  
  
Line 52: Line 64:
 
| the id of the record in the data catalog
 
| the id of the record in the data catalog
 
|-
 
|-
| Record ID
+
| Knowledge Base UUID
| record_id
+
| knowledge_base_id
 
| mandatory
 
| mandatory
| the id of the record in the GRSF knowledge base
+
| the uuid of the record in the GRSF knowledge base
 
|-
 
|-
| Type
+
| Old Status
| type
+
| old_status
 
| mandatory
 
| mandatory
| the type of the resource. It can be one of the following: [stock, fishery]
+
| the old status of the record. The accepted values are: [approved, rejected, pending, hidden, archived]
 
|-
 
|-
| Status
+
| New Status
| status
+
| new_status
 
| mandatory
 
| mandatory
| the new status of the record. The accepted values are: [confirmed, rejected, pending]
+
| the new status of the record. The accepted values are: [approved, rejected, pending, hidden, archived]
 +
|-
 +
| Old Short Name
 +
| short_name_old
 +
| mandatory
 +
| the old short name of the record.
 +
|-
 +
| New Short Name
 +
| short_name_new
 +
| mandatory
 +
| the new short name of the record.
 +
|-
 +
| New value for traceability flag
 +
| traceability_flag
 +
| mandatory
 +
| the updated value for traceability flag
 +
|-
 +
| Administrator name
 +
| administrator_name
 +
| optional
 +
| The name of the administrator performing the change
 
|-
 
|-
 
| Annotation message
 
| Annotation message
Line 71: Line 103:
 
| optional
 
| optional
 
| a short narrative text used for justifying the status change
 
| a short narrative text used for justifying the status change
 +
|-
 +
| Similar records
 +
| similar_records["knowledge_base_id":"...", "merge":false/true]
 +
| optional
 +
| a list of similar records with a merge flag indicating whether they should be merged or not
 +
|-
 +
| Connections
 +
| connections["source_knowledge_base_id":"...","dest_knowledge_base_id":"...", "remove":false/true]
 +
| optional
 +
| a list of connections that refer to the exploited resources of the record. The resources that are added here will be added in a list with title connections in the catalog. If there are exploited resources (in the KB) and they are not included in the connections list then they will remain as potential exploiting resources. If remove flag is set to true for a record then it will be totally removed (from connections and exploiting resources),
 
|}
 
|}
 +
  
 
An indicative example of a JSON object that can be used as input is the following.
 
An indicative example of a JSON object that can be used as input is the following.
Line 77: Line 120:
 
<source lang="javascript">
 
<source lang="javascript">
 
{
 
{
  "catalog_id" : "cat-1234-5678-90",
+
"catalog_id": "catalog_id_123",
  "record_id" : "rec-1234-5678-90",
+
"knowledge_base_id": "3f7b6750-1775-3a2f-a4db-069cbaf4b086",
  "type" : "stock",
+
"old_status": "pending",
  "status" : "rejected"
+
"new_status": "pending",
  "annotation_msg" : "the corresponding values for exploitation rate are missing"  
+
"annotation_message": "",
 +
"short_name_old": "Pharaoh cuttlefish - India",
 +
"short_name_new": "Pharaoh cuttlefish - India",
 +
"traceability_flag": true,
 +
"administrator_name": "Yannis Marketakis",
 +
"similar_grsf_records": [{
 +
        "knowledge_base_id": "9ff63706-ae9e-30e6-8498-425c3274e97e",
 +
        "merge": false
 +
    },
 +
    {
 +
        "knowledge_base_id": "9f5c69c4-b262-31c5-abf1-15a9f1c6622b",
 +
        "merge": false
 +
    }],
 +
    "connections": [{
 +
        "source_knowledge_base_id": "3f7b6750-1775-3a2f-a4db-069cbaf4b086",
 +
        "dest_knowledge_base_id": "e63f87ab-c00a-3a1e-a852-156667ee8049",
 +
        "remove" : false
 +
    },
 +
    {
 +
        "source_knowledge_base_id": "3f7b6750-1775-3a2f-a4db-069cbaf4b086",
 +
        "dest_knowledge_base_id": "491323fc-3cdf-36ab-8c8c-7c6f4262b91c",
 +
        "remove" : true,
 +
    }
 +
    ]
 
}
 
}
 
</source>
 
</source>
  
=== Service response ===  
+
===== Service Response =====
  
 
The service returns the response as a JSON object (similar to the input). The following table shows the fields of the object that are returned as a response.
 
The service returns the response as a JSON object (similar to the input). The following table shows the fields of the object that are returned as a response.
Line 98: Line 164:
 
| the id of the record in the data catalog
 
| the id of the record in the data catalog
 
|-
 
|-
| Record ID
+
| Knowledge Base UUID
| record_id
+
| knowledge_base_id
 
| the id of the record in the GRSF knowledge base
 
| the id of the record in the GRSF knowledge base
 
|-
 
|-
| Type
+
| New Status
| type
+
| new_status
| the type of the resource. It can be one of the following: [stock, fishery]
+
| the updated status of the record.
 
|-
 
|-
| Status
+
| New Short name
| status
+
| short_name_new
| the updated status of the record. It can one of the following: [confirmed, rejected, pending]
+
| the updated short name of the record.
 
|-
 
|-
| Annotation message
+
| Update Result
| annotation_msg
+
| update_result
| the short narrative text used for justifying the status change
+
| the result of the update process
 
|-
 
|-
 
| Error message
 
| Error message
| error
+
| error_message
 
| contains the message describing the fault/error that has occurred. If no error emerged then this field is empty.
 
| contains the message describing the fault/error that has occurred. If no error emerged then this field is empty.
 
|}
 
|}
Line 123: Line 189:
 
<source lang="javascript">
 
<source lang="javascript">
 
{
 
{
   "catalog_id" : "cat-1234-5678-90",
+
   "catalog_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
   "record_id" : "rec-1234-5678-90",
+
   "knowledge_base_id": "15296975-54f5-37f5-8033-84cf7d09c3f5",
   "type" : "stock",
+
   "new_status": "approved",
   "status" : "reject"
+
   "short_name_new": "Thunnus albacares North-East Pacific",
   "annotation_msg" : "the corresponding values for exploitation rate are missing"
+
   "update_result": true,
   "error" : "The record ID does not exist in the GRSF KB"
+
   "error_message": null
 
}
 
}
 
</source>
 
</source>
Line 134: Line 200:
 
Apart from returned JSON the service uses HTTP codes for indicating whether the request has been processed successfully or not. More specifically the following HTTP codes are returned:
 
Apart from returned JSON the service uses HTTP codes for indicating whether the request has been processed successfully or not. More specifically the following HTTP codes are returned:
  
* '''200''': it is returned if the request has been processed successfully, and the status of the corresponding record has been updated
+
* '''200''': it is returned if the request has been processed successfully, and the record has been updated
 
* '''400''': it is returned if any of the given parameters that are mandatory is missing or contains incorrect values (i.e. a wrong status value)
 
* '''400''': it is returned if any of the given parameters that are mandatory is missing or contains incorrect values (i.e. a wrong status value)
 
* '''404''': it is returned if the record to be updated does not exist (i.e. cannot find the record ID in the GRSF KB)
 
* '''404''': it is returned if the record to be updated does not exist (i.e. cannot find the record ID in the GRSF KB)
 
* '''500''': it is returned for any error that might occur when updating the records in the GRSF KB
 
* '''500''': it is returned for any error that might occur when updating the records in the GRSF KB
  
=== Service usage ===
+
==== Revert endpoint ====
  
The following JAVA application can be used for contacting the grsf-services-updater service for updating the status of a GRSF record.
+
It is a POST service that allows reverting a request for merging records
<source lang=java>
+
import org.apache.commons.httpclient.HttpClient;
+
import org.apache.commons.httpclient.HttpException;
+
import org.apache.commons.httpclient.HttpStatus;
+
import org.apache.commons.httpclient.MultiThreadedHttpConnectionManager;
+
import org.apache.commons.httpclient.methods.ByteArrayRequestEntity;
+
import org.apache.commons.httpclient.methods.PostMethod;
+
import org.json.simple.JSONObject;
+
  
/**
+
===== Service Request =====
* @author Yannis Marketakis (marketak 'at' forth 'dot' ics 'dot' gr)
+
The service accepts as input JSON objects. Some of the fields in the object are mandatory while others are optional. The following table lists the fields of the JSON objects.  
*/
+
public class Client {
+
    private static final String SERVICE_BASE_URL="http://localhost:8080/grsf-services-updater"; //the URL of the deployed service
+
    private static final String SERVICE_POST_METHOD="service/updater/post";
+
   
+
    public static void main(String[] args){
+
        MultiThreadedHttpConnectionManager connectionManager=new MultiThreadedHttpConnectionManager();
+
        connectionManager.getParams().setSoTimeout(15000);
+
        HttpClient httpClient=new HttpClient(connectionManager);
+
       
+
        PostMethod method=new PostMethod(SERVICE_BASE_URL+"/"+SERVICE_POST_METHOD);
+
        method.setRequestHeader("Content-type", "application/json");
+
  
        JSONObject json=new JSONObject();
+
{| class="wikitable"
        json.put("catalog_id", "cat-123");
+
! style="text-align: center; font-weight: bold;" | Name
        json.put("record_id", "SKJ+IOTC");
+
! style="text-align: center; font-weight: bold;" | Api Name (JSON)
        json.put("type", "stock");
+
! style="text-align: center; font-weight: bold;" | Mandatory/Optional
        json.put("status", "pending");
+
! style="text-align: center; font-weight: bold;" | Description
 +
|-
 +
| Knowledge Base UUID
 +
| knowledge_base_id
 +
| mandatory
 +
| the uuid of the record in the GRSF knowledge base that initiated the merging event (the record that was updated when merging with other similar records was decided),
 +
|-
 +
| Administrator name
 +
| administrator_name
 +
| optional
 +
| The name of the administrator performing the change
 +
|}
  
        method.setRequestEntity(new ByteArrayRequestEntity(json.toJSONString().getBytes()));
+
 
        byte[] responseBody=null;
+
An indicative example of a JSON object that can be used as input is the following.
       
+
 
        try{
+
<source lang="javascript">
            int statusCode = httpClient.executeMethod(method);
+
{
            if (statusCode != HttpStatus.SC_OK && statusCode != HttpStatus.SC_CREATED) {
+
"knowledge_base_id": "3f7b6750-1775-3a2f-a4db-069cbaf4b086",
                System.out.println("Method failed: " + method.getStatusLine()+
+
"administrator_name": "Yannis Marketakis",
                            "; Response bpdy: "+method.getResponseBodyAsString());
+
                method.releaseConnection();
+
                throw new Exception("Method failed: " + method.getStatusLine()+
+
                                    "; Response body: "+new String(method.getResponseBody()));
+
            }
+
            responseBody = method.getResponseBody();
+
            System.out.println(new String(responseBody));
+
        }catch (HttpException ex) {
+
                System.out.println("Fatal protocol violation: "+ex);
+
                method.releaseConnection();
+
        }catch (Exception ex) {
+
                System.out.println("Fatal transport error: "+ex);
+
                method.releaseConnection();
+
        }
+
        method.releaseConnection();
+
    }
+
 
}
 
}
 
</source>
 
</source>
  
For maven projects you should also use the following maven dependencies
+
===== Service Response =====
<source lang="xml">
+
 
<dependency>
+
The service returns the response as a JSON object (similar to the input). The following table shows the fields of the object that are returned as a response.
  <groupId>commons-httpclient</groupId>
+
 
  <artifactId>commons-httpclient</artifactId>
+
{| class="wikitable"
  <version>3.1</version>
+
! style="text-align: center; font-weight: bold;" | Name
</dependency>
+
! style="text-align: center; font-weight: bold;" | Api Name (JSON)
<dependency>
+
! style="text-align: center; font-weight: bold;" | Description
  <groupId>com.googlecode.json-simple</groupId>
+
|-
  <artifactId>json-simple</artifactId>
+
| Knowledge Base UUID
  <version>1.1.1</version>
+
| knowledge_base_id
</dependency>
+
| the id of the record in the GRSF knowledge base
 +
|-
 +
| Update Result
 +
| update_result
 +
| the result of the update process
 +
|-
 +
| Error message
 +
| error_message
 +
| contains the message describing the fault/error that has occurred. If no error emerged then this field is empty.
 +
|}
 +
 
 +
An indicative example of a JSON object that can be used as input is the following.
 +
 
 +
<source lang="javascript">
 +
{
 +
  "knowledge_base_id": "15296975-54f5-37f5-8033-84cf7d09c3f5",
 +
  "update_result": false,
 +
  "error_message": "There knowledge base UUID is missing"
 +
}
 
</source>
 
</source>
 +
 +
Apart from returned JSON the service uses HTTP codes for indicating whether the request has been processed successfully or not. More specifically the following HTTP codes are returned:
 +
 +
* '''200''': it is returned if the request has been processed successfully, and the change was reverted
 +
* '''400''': it is returned if any of the given parameters that are mandatory is missing or contains incorrect values
 +
* '''404''': it is returned if the record to be reverted does not exist
 +
* '''500''': it is returned for any error that might occur while reverting merge events in the GRSF KB
 +
 +
==== Info endpoint ====
 +
 +
It is an GET service that reports the following information about the service endpoint:
 +
 +
* service name and version
 +
* triplestore used information (host and port)
 +
* publisher API information (host and catalog scope)
 +
 +
===== Service Response =====
 +
 +
The service returns the response as a JSON object (similar to the input). The following table shows the fields of the object that are returned as a response.
 +
 +
{| class="wikitable"
 +
! style="text-align: center; font-weight: bold;" | Name
 +
! style="text-align: center; font-weight: bold;" | Api Name (JSON)
 +
! style="text-align: center; font-weight: bold;" | Description
 +
|-
 +
| Service Name
 +
| name
 +
| the name of the service (i.e. grsf-services-updater)
 +
|-
 +
| Service Version
 +
| version
 +
| the vesion of the service (i.e. 1.2.0)
 +
|-
 +
| Documentation
 +
| documentation
 +
| points to the documentation page of the service (i.e. this page or documentation in swagger)
 +
|-
 +
| Triplestore Information
 +
| triplestore: {"host":"...", "port":...}
 +
| contains information about the triplestore that is used
 +
|-
 +
| Catalog Information
 +
| catalog_info: {"host":"...", "scope":...}
 +
| contains information about the publisher API used and scope of the catalog
 +
|}
 +
 +
An indicative example of a JSON object that can be used as input is the following.
 +
 +
<source lang="javascript">
 +
{
 +
  "name": "grsf-services-updater",
 +
  "version": "1.2.0",
 +
  "documentation": "http://app.swaggerhub/apis/...",
 +
  "triplestore": {
 +
    "host": "http://example.com/",
 +
    "port": 1234
 +
  },
 +
  "catalog_info": {
 +
    "host": "http://example.com/",
 +
    "scope": "ADMIN"
 +
  }
 +
}
 +
</source>
 +
 +
Apart from returned JSON the service uses HTTP codes for indicating whether the request has been processed successfully or not. More specifically the following HTTP codes are returned:
 +
 +
* '''200''': it is returned if the request has been processed successfully, and the information are shown
 +
 +
=== Service Documentation ===
 +
 +
The detailed documentation of the service can be found in Swagger
 +
https://app.swaggerhub.com/apis/ymark/grsf-services-updater
  
 
== Links ==
 
== Links ==
Line 218: Line 349:
 
* https://support.d4science.org/issues/5600
 
* https://support.d4science.org/issues/5600
 
* https://support.d4science.org/issues/5890
 
* https://support.d4science.org/issues/5890
 +
* https://support.d4science.org/issues/6259

Latest revision as of 10:45, 8 February 2018

GRSF-services

In this page we describe the components that are responsible for interacting with the gCube infrastructure for performing various activities about GRSF records. GRSF records are handled as dataset resources and are stored in the data catalogue. The following image depicts a high level view of the architecture of components that are exploited for constructing the GRSF KB, publishing GRSF records and updating them. In the sequel we will focus and describe the components grsf-services-core and grsf-services-updater.

GRSF components.jpg

grsf-services-core

This component is responsible for retrieving individual records from the GRSF KB and publish them in the GRSF data catalogue. For this reason it uses the particular service (which is described at GCube_Data_Catalogue_for_GRSF). Since the service is accepting incoming records (either for stocks or fisheries) as JSON objects, the main functionality of the grsf-services-core component is to act a a bridge between the GRSF KB and the GRSF data catalogue. The corresponding steps for publishing a set of records is described below (and in the corresponding part of the sequence diagram).

  1. The grsf-services-core component fetches all the GRSF records and their corresponding information from the GRSF KB. Since the GRSF KB is a semantic warehouse, its contents are stored as a set of RDF triples; therefore in order to fetch them a particular SPARQL query has to be formulated and submitted to the GRSF KB.
  2. After fetching all the GRSF records (in terms of RDF triples), they have to be transformed so that they can be published through the publishing service of the GRSF data catalogue. The services accepts JSON object, therefore the RDF triples are transformed accordingly with respect to the expected metadata (which are described here).
  3. The grsf-services-core component publishes the transformed JSON objects and retrieves the results.

GRSF records publishing.jpg

The component is being delivered as a software library. It is being triggered from MatWare after the construction of the GRSF KB.

grsf-services-updater

This component is responsible for updating the status of a record, when the users requires so. More specifically the component is delivered as a service, that accepts incoming requests containing the record that will be updated, with its accompanying information (the new status, a narrative text describing the status update). Once a request has been received the service will update the contents in the GRSF KB, and return a response message information the caller for the results. The communication messages for the service are formulated JSON objects. The service allows updating the following fields of a record:

  • Updates the status of a record (available statuses: pending, approved, rejected, hidden, archived).
  • Updates the short name of a record.
  • Updates the tracability flag of a record.
  • Updates the list of connected exploiting resources.
  • Defines alternative merging operations with similar records.

GRSF records updating.jpg

Check service availability

In order to check that the service is up and running you can use the following url

[GRSF_SERVICES-CORE BASE_URL]/grsf-services-updater

This will show a landing page with instructions for using the service indicating that the service is up and running.

Service endpoints

The service exposes the following endpoints:

  • updater: allows updating a record.
  • revert: allows reverting the proposed merging of records.
  • info: shows detailed information about the services (triplestore and publisher information).

Updater endpoint

It is a POST service that allows updating various infomation about a record.

Service Request

The service accepts as input JSON objects. Some of the fields in the object are mandatory while others are optional. The following table lists the fields of the JSON objects.

Name Api Name (JSON) Mandatory/Optional Description
Catalogue ID catalog_id mandatory the id of the record in the data catalog
Knowledge Base UUID knowledge_base_id mandatory the uuid of the record in the GRSF knowledge base
Old Status old_status mandatory the old status of the record. The accepted values are: [approved, rejected, pending, hidden, archived]
New Status new_status mandatory the new status of the record. The accepted values are: [approved, rejected, pending, hidden, archived]
Old Short Name short_name_old mandatory the old short name of the record.
New Short Name short_name_new mandatory the new short name of the record.
New value for traceability flag traceability_flag mandatory the updated value for traceability flag
Administrator name administrator_name optional The name of the administrator performing the change
Annotation message annotation_msg optional a short narrative text used for justifying the status change
Similar records similar_records["knowledge_base_id":"...", "merge":false/true] optional a list of similar records with a merge flag indicating whether they should be merged or not
Connections connections["source_knowledge_base_id":"...","dest_knowledge_base_id":"...", "remove":false/true] optional a list of connections that refer to the exploited resources of the record. The resources that are added here will be added in a list with title connections in the catalog. If there are exploited resources (in the KB) and they are not included in the connections list then they will remain as potential exploiting resources. If remove flag is set to true for a record then it will be totally removed (from connections and exploiting resources),


An indicative example of a JSON object that can be used as input is the following.

{
	"catalog_id": "catalog_id_123",
	"knowledge_base_id": "3f7b6750-1775-3a2f-a4db-069cbaf4b086",
	"old_status": "pending",
	"new_status": "pending",
	"annotation_message": "",
	"short_name_old": "Pharaoh cuttlefish - India",
	"short_name_new": "Pharaoh cuttlefish - India",
	"traceability_flag": true, 
	"administrator_name": "Yannis Marketakis",
	"similar_grsf_records": [{
        "knowledge_base_id": "9ff63706-ae9e-30e6-8498-425c3274e97e",
        "merge": false
    },
    {
        "knowledge_base_id": "9f5c69c4-b262-31c5-abf1-15a9f1c6622b",
        "merge": false
    }], 
    "connections": [{
        "source_knowledge_base_id": "3f7b6750-1775-3a2f-a4db-069cbaf4b086",
        "dest_knowledge_base_id": "e63f87ab-c00a-3a1e-a852-156667ee8049",
        "remove" : false
    },
    {
        "source_knowledge_base_id": "3f7b6750-1775-3a2f-a4db-069cbaf4b086",
        "dest_knowledge_base_id": "491323fc-3cdf-36ab-8c8c-7c6f4262b91c",
        "remove" : true,
    }
    ]
}
Service Response

The service returns the response as a JSON object (similar to the input). The following table shows the fields of the object that are returned as a response.

Name Api Name (JSON) Description
Catalogue ID catalog_id the id of the record in the data catalog
Knowledge Base UUID knowledge_base_id the id of the record in the GRSF knowledge base
New Status new_status the updated status of the record.
New Short name short_name_new the updated short name of the record.
Update Result update_result the result of the update process
Error message error_message contains the message describing the fault/error that has occurred. If no error emerged then this field is empty.

An indicative example of a JSON object that can be used as input is the following.

{
  "catalog_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "knowledge_base_id": "15296975-54f5-37f5-8033-84cf7d09c3f5",
  "new_status": "approved",
  "short_name_new": "Thunnus albacares North-East Pacific",
  "update_result": true,
  "error_message": null
}

Apart from returned JSON the service uses HTTP codes for indicating whether the request has been processed successfully or not. More specifically the following HTTP codes are returned:

  • 200: it is returned if the request has been processed successfully, and the record has been updated
  • 400: it is returned if any of the given parameters that are mandatory is missing or contains incorrect values (i.e. a wrong status value)
  • 404: it is returned if the record to be updated does not exist (i.e. cannot find the record ID in the GRSF KB)
  • 500: it is returned for any error that might occur when updating the records in the GRSF KB

Revert endpoint

It is a POST service that allows reverting a request for merging records

Service Request

The service accepts as input JSON objects. Some of the fields in the object are mandatory while others are optional. The following table lists the fields of the JSON objects.

Name Api Name (JSON) Mandatory/Optional Description
Knowledge Base UUID knowledge_base_id mandatory the uuid of the record in the GRSF knowledge base that initiated the merging event (the record that was updated when merging with other similar records was decided),
Administrator name administrator_name optional The name of the administrator performing the change


An indicative example of a JSON object that can be used as input is the following.

{
	"knowledge_base_id": "3f7b6750-1775-3a2f-a4db-069cbaf4b086",
	"administrator_name": "Yannis Marketakis",
}
Service Response

The service returns the response as a JSON object (similar to the input). The following table shows the fields of the object that are returned as a response.

Name Api Name (JSON) Description
Knowledge Base UUID knowledge_base_id the id of the record in the GRSF knowledge base
Update Result update_result the result of the update process
Error message error_message contains the message describing the fault/error that has occurred. If no error emerged then this field is empty.

An indicative example of a JSON object that can be used as input is the following.

{
  "knowledge_base_id": "15296975-54f5-37f5-8033-84cf7d09c3f5",
  "update_result": false,
  "error_message": "There knowledge base UUID is missing"
}

Apart from returned JSON the service uses HTTP codes for indicating whether the request has been processed successfully or not. More specifically the following HTTP codes are returned:

  • 200: it is returned if the request has been processed successfully, and the change was reverted
  • 400: it is returned if any of the given parameters that are mandatory is missing or contains incorrect values
  • 404: it is returned if the record to be reverted does not exist
  • 500: it is returned for any error that might occur while reverting merge events in the GRSF KB

Info endpoint

It is an GET service that reports the following information about the service endpoint:

  • service name and version
  • triplestore used information (host and port)
  • publisher API information (host and catalog scope)
Service Response

The service returns the response as a JSON object (similar to the input). The following table shows the fields of the object that are returned as a response.

Name Api Name (JSON) Description
Service Name name the name of the service (i.e. grsf-services-updater)
Service Version version the vesion of the service (i.e. 1.2.0)
Documentation documentation points to the documentation page of the service (i.e. this page or documentation in swagger)
Triplestore Information triplestore: {"host":"...", "port":...} contains information about the triplestore that is used
Catalog Information catalog_info: {"host":"...", "scope":...} contains information about the publisher API used and scope of the catalog

An indicative example of a JSON object that can be used as input is the following.

{
  "name": "grsf-services-updater",
  "version": "1.2.0",
  "documentation": "http://app.swaggerhub/apis/...",
  "triplestore": {
    "host": "http://example.com/",
    "port": 1234
  },
  "catalog_info": {
    "host": "http://example.com/",
    "scope": "ADMIN"
  }
}

Apart from returned JSON the service uses HTTP codes for indicating whether the request has been processed successfully or not. More specifically the following HTTP codes are returned:

  • 200: it is returned if the request has been processed successfully, and the information are shown

Service Documentation

The detailed documentation of the service can be found in Swagger https://app.swaggerhub.com/apis/ymark/grsf-services-updater

Links

Related tickets