From a21f25e5e98c41377ef2fb2aab1fc24bce52548a Mon Sep 17 00:00:00 2001 From: Antonin Delpeuch Date: Thu, 10 Nov 2022 15:46:34 +0100 Subject: [PATCH] Impose pre-determined routes instead of announcing them in the manifest (#91) * Impose pre-determined routes rather than announcing them in the manifest, for #84 * Remove mention of iframe * Remove the mention of form elements. Co-authored-by: Fabian Steeg Co-authored-by: Fabian Steeg --- .../flyout-response/valid/example.json | 4 - .../manifest/valid/findthatcharity.json | 1 - .../manifest/valid/geocollider-sinatra.json | 7 +- latest/examples/manifest/valid/getty.json | 8 +- .../examples/manifest/valid/kerameikos.json | 9 +- latest/examples/manifest/valid/kew.json | 21 +-- latest/examples/manifest/valid/lobid-gnd.json | 26 +-- latest/examples/manifest/valid/nomisma.json | 9 +- latest/examples/manifest/valid/occrp.json | 16 +- latest/examples/manifest/valid/wikidata.json | 24 +-- .../suggest-metadata/valid/example.json | 5 - latest/index.html | 163 +++++++----------- latest/schemas/manifest.json | 51 ++---- 13 files changed, 97 insertions(+), 247 deletions(-) delete mode 100644 latest/examples/flyout-response/valid/example.json delete mode 100644 latest/examples/suggest-metadata/valid/example.json diff --git a/latest/examples/flyout-response/valid/example.json b/latest/examples/flyout-response/valid/example.json deleted file mode 100644 index 19dfc74..0000000 --- a/latest/examples/flyout-response/valid/example.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "id": "Q38274", - "html": "

Thai musician

" -} diff --git a/latest/examples/manifest/valid/findthatcharity.json b/latest/examples/manifest/valid/findthatcharity.json index 0825384..f3682e0 100644 --- a/latest/examples/manifest/valid/findthatcharity.json +++ b/latest/examples/manifest/valid/findthatcharity.json @@ -7,7 +7,6 @@ "url": "https://findthatcharity.uk/charity/{id}" }, "preview": { - "url": "https://findthatcharity.uk/preview/charity/{id}", "width": 430, "height": 300 }, diff --git a/latest/examples/manifest/valid/geocollider-sinatra.json b/latest/examples/manifest/valid/geocollider-sinatra.json index ffd1dcc..ae6df0b 100644 --- a/latest/examples/manifest/valid/geocollider-sinatra.json +++ b/latest/examples/manifest/valid/geocollider-sinatra.json @@ -7,10 +7,9 @@ "url": "{+id}" }, "suggest": { - "property": { - "service_url": "https://geocollider-sinatra.herokuapp.com", - "service_path": "/suggest" - } + "entity": false, + "property": true, + "type": false }, "defaultTypes": [ { diff --git a/latest/examples/manifest/valid/getty.json b/latest/examples/manifest/valid/getty.json index afa51b7..54ebb47 100644 --- a/latest/examples/manifest/valid/getty.json +++ b/latest/examples/manifest/valid/getty.json @@ -23,15 +23,13 @@ "batchSize": 50, "preview": { "height": 200, - "url": "https://services.getty.edu/vocab/reconcile/preview{?id}", "width": 350 }, "schemaSpace": "http://vocab.getty.edu/doc/#The_Getty_Vocabularies_and_LOD", "suggest": { - "property": { - "service_path": "/suggest/property", - "service_url": "https://services.getty.edu/vocab/reconcile" - } + "entity": false, + "property": true, + "type": false }, "view": { "url": "http://vocab.getty.edu/page/{id}" diff --git a/latest/examples/manifest/valid/kerameikos.json b/latest/examples/manifest/valid/kerameikos.json index 4aa5caf..76f1591 100644 --- a/latest/examples/manifest/valid/kerameikos.json +++ b/latest/examples/manifest/valid/kerameikos.json @@ -61,15 +61,12 @@ } ], "preview": { - "url": "http://kerameikos.org/apis/reconcile/preview{?id}", "height": 90, "width": 320 }, "suggest": { - "entity": { - "service_url": "http://kerameikos.org/apis/reconcile", - "service_path": "/suggest/entity", - "flyout_service_path": "/flyout{?id}" - } + "entity": true, + "property": false, + "type": false } } diff --git a/latest/examples/manifest/valid/kew.json b/latest/examples/manifest/valid/kew.json index b4d9fb8..761cbce 100644 --- a/latest/examples/manifest/valid/kew.json +++ b/latest/examples/manifest/valid/kew.json @@ -12,24 +12,9 @@ "height": 400 }, "suggest": { - "type": { - "service_url": "http://data1.kew.org", - "service_path": "/reconciliation/reconcile/IpniName/suggestType", - "flyout_service_url": "http://data1.kew.org", - "flyout_service_path": "/reconciliation/reconcile/IpniName/flyoutType/${id}" - }, - "property": { - "service_url": "http://data1.kew.org", - "service_path": "/reconciliation/reconcile/IpniName/suggestProperty", - "flyout_service_url": "http://data1.kew.org", - "flyout_service_path": "/reconciliation/reconcile/IpniName/flyoutProperty/${id}" - }, - "entity": { - "service_url": "http://data1.kew.org", - "service_path": "/reconciliation/reconcile/IpniName", - "flyout_service_url": "http://data1.kew.org", - "flyout_service_path": "/reconciliation/reconcile/IpniName/flyout/${id}" - } + "type": true, + "property": true, + "entity": true }, "defaultTypes": [ { diff --git a/latest/examples/manifest/valid/lobid-gnd.json b/latest/examples/manifest/valid/lobid-gnd.json index efea199..c496d8f 100644 --- a/latest/examples/manifest/valid/lobid-gnd.json +++ b/latest/examples/manifest/valid/lobid-gnd.json @@ -48,8 +48,7 @@ }, "preview": { "height": 100, - "width": 320, - "url": "https://lobid.org/gnd/{{id}}.preview" + "width": 320 }, "extend": { "property_settings": [ @@ -78,26 +77,11 @@ ] } ], - "propose_properties": { - "service_url": "https://lobid.org", - "service_path": "/gnd/reconcile/properties" - } + "propose_properties": true }, "suggest": { - "property": { - "service_url": "https://lobid.org/gnd/reconcile", - "service_path": "/suggest/property", - "flyout_service_path": "/flyout/property?id=${id}" - }, - "entity": { - "service_url": "https://lobid.org/gnd/reconcile", - "service_path": "/suggest/entity", - "flyout_service_path": "/flyout/entity?id=${id}" - }, - "type": { - "service_url": "https://lobid.org/gnd/reconcile", - "service_path": "/suggest/type", - "flyout_service_path": "/flyout/type?id=${id}" - } + "property": true, + "entity": true, + "type": true } } diff --git a/latest/examples/manifest/valid/nomisma.json b/latest/examples/manifest/valid/nomisma.json index 3983ed1..3a2f84c 100644 --- a/latest/examples/manifest/valid/nomisma.json +++ b/latest/examples/manifest/valid/nomisma.json @@ -101,15 +101,12 @@ } ], "preview": { - "url": "http://nomisma.org/apis/reconcile/preview?id={{id}}", "height": 90, "width": 320 }, "suggest": { - "entity": { - "service_url": "http://nomisma.org/apis/reconcile", - "service_path": "/suggest/entity", - "flyout_service_path": "/flyout?id=${id}" - } + "entity": true, + "property": false, + "type": false } } diff --git a/latest/examples/manifest/valid/occrp.json b/latest/examples/manifest/valid/occrp.json index f87ee6a..eb1a8a5 100644 --- a/latest/examples/manifest/valid/occrp.json +++ b/latest/examples/manifest/valid/occrp.json @@ -7,23 +7,13 @@ "url": "https://aleph.occrp.org/entities/{{id}}" }, "preview": { - "url": "https://aleph.occrp.org/entities/{{id}}", "width": 800, "height": 400 }, "suggest": { - "entity": { - "service_url": "https://aleph.occrp.org", - "service_path": "/api/freebase/suggest?api_key=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1IjpudWxsLCJleHAiOjE1NzEzMTQ5MzQsInIiOlsxXSwiYSI6ZmFsc2UsInMiOiIvYXBpL2ZyZWViYXNlL3N1Z2dlc3QifQ.LullhAvG1hGfMnaVpPjOwIUnt-BOpO8_xHxSoGieMeQ" - }, - "type": { - "service_url": "https://aleph.occrp.org", - "service_path": "/api/freebase/type" - }, - "property": { - "service_url": "https://aleph.occrp.org", - "service_path": "/api/freebase/property" - } + "entity": true, + "type": true, + "property": true }, "defaultTypes": [ { diff --git a/latest/examples/manifest/valid/wikidata.json b/latest/examples/manifest/valid/wikidata.json index ff641a7..9755dff 100644 --- a/latest/examples/manifest/valid/wikidata.json +++ b/latest/examples/manifest/valid/wikidata.json @@ -2,7 +2,6 @@ "versions": ["0.1", "0.2"], "name": "Wikidata (en)", "preview": { - "url": "https://tools.wmflabs.org/openrefine-wikidata/en/preview?id={{id}}", "width": 400, "height": 100 }, @@ -69,10 +68,7 @@ "default": false } ], - "propose_properties": { - "service_url": "https://tools.wmflabs.org/openrefine-wikidata", - "service_path": "/en/propose_properties" - } + "propose_properties": true }, "defaultTypes": [ { @@ -84,21 +80,9 @@ "url": "https://www.wikidata.org/wiki/{{id}}" }, "suggest": { - "type": { - "service_url": "https://tools.wmflabs.org/openrefine-wikidata", - "service_path": "/en/suggest/type", - "flyout_service_path": "/en/flyout/type?id=${id}" - }, - "entity": { - "service_url": "https://tools.wmflabs.org/openrefine-wikidata", - "service_path": "/en/suggest/entity", - "flyout_service_path": "/en/flyout/entity?id=${id}" - }, - "property": { - "service_url": "https://tools.wmflabs.org/openrefine-wikidata", - "service_path": "/en/suggest/property", - "flyout_service_path": "/en/flyout/property?id=${id}" - } + "type": true, + "entity": true, + "property": true }, "identifierSpace": "http://www.wikidata.org/entity/" } diff --git a/latest/examples/suggest-metadata/valid/example.json b/latest/examples/suggest-metadata/valid/example.json deleted file mode 100644 index ed92a39..0000000 --- a/latest/examples/suggest-metadata/valid/example.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "service_url": "https://example.com/api", - "service_path": "/suggest", - "flyout_service_path": "/suggest/flyout/${id}" -} diff --git a/latest/index.html b/latest/index.html index 672ddc9..ed5af6d 100644 --- a/latest/index.html +++ b/latest/index.html @@ -216,9 +216,11 @@

0.2

This Draft

-

- No changes made yet. -

+

Collection of changes which make the API conform to the REST principles.

+
    +
  • Remove support for flyouts;
    • +
  • The endpoints of various sub-services are no longer configurable, but determined by the root reconciliation endpoint.
    • +
@@ -372,19 +374,19 @@

Service Manifest

An optional string which describes the version of the software exposing this service. This is not to be confused with versions which is about the versions of the reconciliation API supported by the service;
view
An optional object which contains a single field url. Its value is a URI template for entities;
-
feature_view +
feature_view
An optional object which contains a single field url. Its value is a URI template for matching features;
preview
-
A preview metadata, supplied if the service offers a preview service;
+
A preview metadata object, supplied if the service offers a preview service;
suggest
An optional object which may contain the following fields, depending on which suggest services are offered:
entity
-
A suggest metadata for auto-suggestion of entities;
+
A boolean indicating if the service supports auto-suggestion of entities;
property
-
A suggest metadata for auto-suggestion of properties;
+
A boolean indicating if the service supports auto-suggestion of properties;
type
-
A suggest metadata for auto-suggestion of types.
+
A boolean indicating if the service supports auto-suggestion of types;
extend
@@ -403,6 +405,32 @@

Service Manifest


       

       
+      

+        
Overview of Possible Routes

+        

+          We give here an overview of the routes that reconciliation services MUST and MAY implement. They are all relative to the root endpoint, which we assume here to be /.
+        

+        

+        

+           
/

+           
The root endpoint, which supports the GET method and returns the service manifest. Services MUST support this route;

+           
/reconcile

+           
The route used to submit reconciliation query batches, with the POST method. Services MUST support this route;

+           
/suggest/entity

+           
The route used for auto-completion of entities, with the GET method. Services MAY support this route, as indicated  in their manifest;

+           
/suggest/property

+           
The route used for auto-completion of properties, with the GET method. Services MAY support this route, as indicated in their manifest;

+           
/suggest/type

+           
The route used for auto-completion of types, with the GET method. Services MAY support this route, as indicated in their manifest;

+           
/preview

+           
The route used to preview an entity, with the GET method. Services MAY support this route, depending on the presence of a preview metadata object in their manifest;

+           
/extend

+           
The route used to submit data extension queries, with the POST method. Services MAY support this route, depending on the presence of a data extension metadata object in their manifest;

+           
/extend/propose

+           
The route used to obtain data extension property proposals, with the GET method. Services MAY support this route, following what their data extension metadata object in their manifest indicates.

+        

+       

+      

       

         
HTTP(S) Access

 	

@@ -581,27 +609,15 @@ 
Sending Reconciliation Queries to a Service

 	  reconciliation result batches over HTTP.
 	

 	

-          A reconciliation service MUST support HTTP POST requests on its endpoint with
-          application/x-www-form-urlencoded bodies containing a
-          reconciliation query batch (serialized in JSON) in a form element named queries.
+          A reconciliation service MUST support HTTP POST requests at the route /reconcile (relative to its endpoint) with
+          application/json bodies containing a
+          reconciliation query batch.
         

         

-          
POST / queries=<URL-encoded reconciliation query batch>

-        

-        

-          Similarly, a reconciliation service SHOULD support HTTP GET requests with a
-          reconciliation query batch in a query string parameter named queries.
-        

-        

-          
GET /?queries=<URL-encoded reconciliation query batch>

+          
POST /reconcile <reconciliation query batch>

         

 	

-	   In both cases, the service returns the corresponding query batch serialized in JSON.
-	

-	

-	   The POST method is the primary way to send reconciliation queries to a service since 
-	   it does not restrict the length of the query batches. The GET method is useful for
-	   interactive debugging of reconciliation queries in a web browser, for instance.
+	   The service returns the corresponding query batch serialized in JSON.
 	

       

       

@@ -649,13 +665,10 @@ 
Preview Service

       
Preview Metadata

       
Reconciliation services MAY offer a preview service by providing the preview metadata as an object stored in the service manifest under the key preview. It consists of the following fields, all mandatory:
         

-          
url

-          
A URI template containing the id variable such that expanding the template with id set to an entity identifier yields the preview URL for that entity. This preview URL MUST resolve to an HTML page summarizing the entity.
-It SHOULD render appropriately in an <iframe> whose dimensions are specified by the service in the following fields;

           
width

-          
The width in pixels of the <iframe> element where to render an entity preview;

+          
The width in pixels of the viewport where to render an entity preview;

           
height

-          
The height in pixels of the same <iframe>.

+          
The height in pixels of the same viewport.

         

       

       

@@ -665,10 +678,11 @@ 
Preview Metadata

       

       

       
Preview Queries

-      
A preview service is queried by resolving the preview URL for an entity. The URL must resolve to an HTML document.
+      
A preview service is queried by resolving the URI template /preview?id={id} relative to the reconciliation endpoint, where id is subsituted by the entity identifier. The URL must resolve to an HTML document,
+        which MUST be viewable in an HTML viewport whose dimensions are determined by the preview metadata.
       

       

-        For instance, assuming the example preview metadata above, the service could respond to a preview request as follows:
+        For instance, assuming that the reconciliation API is running at /api and serves the example preview metadata above, the service could respond to a preview request as follows:
        
        

       

@@ -682,28 +696,18 @@ 
Suggest Services

         A reconciliation service can offer a suggest service for any of these three classes. For instance, a service which only exposes a single type might not want to expose a suggest service for types.
         These suggest services can be used by clients to let users select an entity, property or type manually, at various stages of their reconciliation workflows.
         Suggest services for entities, properties and types are declared independently
-        in the service manifest by providing a suggest metadata for them.
+        in the service manifest.
       

       

-      
Suggest Metadata

+      
Suggest Endpoints

       

-        A suggest metadata object consists of the following fields:
+        When supported, the suggest endpoints are located at the following URIs, relative to the service's root endpoint:
         

-          
service_url

-          
The base URL for the suggest service;

-          
service_path

-          
A URL path which will be concatenated to the service_url to obtain the full URL of the suggest service;

-          
flyout_service_url

-          
The base URL for the flyout service. If none is provided, it is assumed to be identical to service_url;

-          
flyout_service_path

-          
An optional URL path which will be concatenated to the flyout_service_url to obtain the full URL of the flyout service. The absence of this parameter indicates that no flyout service is associated with this suggest service.

+          
/suggest/entity

+          
/suggest/property

+          
/suggest/type

         

       

-      

-        For instance, a suggest metadata could be as follows:
-        

-	Such a metadata indicates that a suggest service is available at https://example.com/api/suggest with an associated flyout endpoint at https://example.com/api/suggest/flyout/${id}.
-      

       

       

       
Suggest Queries

@@ -768,35 +772,6 @@ 
General Expectations about Suggest Services

           As the prefix name suggests, suggest services are expected to perform prefix search on their database of records, such that a suggest service can be used to provide auto-completion as users type names or identifiers in a field.
         

       
      
-      

-      
Flyout Services

-        

-          A flyout service provides small previews of suggested elements.
-          These previews are designed to be shown when hovering a suggested element.
-	  When a suggest service supports flyout, it declares the flyout endpoint in its suggest metadata.
-        

-	

-	  A preview for a suggested entity, property or type can then be obtained at the flyout endpoint by replacing ${id}
-	  by the identifier for the entity, property or type, encoded as a URI component. Upon a GET query to this URL, the service returns a JSON response
-	  consisting of an object with the following fields:
-	  

-	    
id

-	    
The identifier supplied in the URL;

-	    
html

-	    
A string containing HTML code that can be used to display a small preview alongside the suggested entity, property or type.

-	  

-	

-	

-          For instance, if a service's flyout endpoint is https://example.com/suggest/entities/flyout?id=${id},
-	  then by retrieving https://example.com/suggest/entities/flyout?id=Q38274, one might get the following
-	  response:
-          

-	

-	

-	  Flyout services were used by Freebase and are mostly redundant with the description field in suggest responses.
-	  Given that they allow services to return arbitrary HTML content, they also pose a security threat to clients. It is therefore proposed          that this functionality is dropped in the future.
-	

-      

     

     

       
Data Extension Service

@@ -819,15 +794,7 @@ 
Data Extension Metadata

           The data extension metadata is an object stored in the service manifest in the extend field. It consists of the following settings, all optional:
           

             
propose_properties

-            
A service path object defining a URL which implements data extension property proposal, which consists of:
-              

-                
service_url

-                
The root URL of the service;

-                
service_path

-                
The path to the endpoint for property proposals.

-              

-              The full URL for data extension property proposals is obtained by concatenating these two fields.
-            

+            
A boolean indicating if the service supports data extension property proposal;

             
property_settings

             
An array of data extension property settings.

           

@@ -860,16 +827,14 @@ 
Data Extension Property Proposals

           A data extension property proposal service returns properties for a given type identifier.
         

         

-          The service MUST support HTTP GET requests with a `type` query string parameter.
-        

-        

-          The service SHOULD support an optional `limit` query string parameter to control the number of proposed properties.
+          If the reconciliation service supports data extension property proposals, it MUST support HTTP GET requests to the endpoint /extend/propose (relative to the reconciliation endpoint) with a type query string parameter
+containing a type identifier.
         

         

-          The service URL and path are declared in the data extension metadata of the service manifest.
+          The service SHOULD support an optional limit query string parameter to control the number of proposed properties.
         

         

-          
GET /properties?type=<type identifier>[&limit=<limit>]

+          
GET /extend/propose?type=<type identifier>[&limit=<limit>]

         

         

           A data extension property proposal response consists of:
@@ -896,19 +861,11 @@ 
Data Extension Query Requests

         

           The fact that a reconciliation service offers data extension MUST be announced by including a data extension metadata in the extend field of the service manifest.
         

-          A data extension service MUST support HTTP POST requests with
-          application/x-www-form-urlencoded bodies containing a
-          data extension query in a form element named extend.
-        

-        

-          
POST / extend=<URL-encoded data extension query>

-        

-        

-          A data extension service SHOULD support HTTP GET requests with a
-          data extension query in a query string parameter named extend.
+          A data extension service MUST support HTTP POST requests at /extend (relative to the reconciliation endpoint) with
+          application/json bodies containing a data extension query.
         

         

-          
GET /?extend=<URL-encoded data extension query>

+          
POST /extend <data extension query>

         

         

           A data extension query consists of:
diff --git a/latest/schemas/manifest.json b/latest/schemas/manifest.json
index 787ba70..70737fa 100644
--- a/latest/schemas/manifest.json
+++ b/latest/schemas/manifest.json
@@ -76,48 +76,26 @@
     "suggest": {
       "type": "object",
       "description": "Settings for the suggest protocol, to auto-complete entities, properties and types",
-      "definitions": {
-        "service_definition": {
-          "type": "object",
-          "properties": {
-            "service_url": {
-              "type": "string"
-            },
-            "service_path": {
-              "type": "string"
-            },
-            "flyout_service_url": {
-              "type": "string"
-            },
-            "flyout_service_path": {
-              "type": "string",
-              "pattern": ".*\\{.*id.*\\}.*"
-            }
-          },
-          "required": []
-        }
-      },
       "properties": {
         "entity": {
-          "$ref": "#/properties/suggest/definitions/service_definition"
+          "type": "boolean",
+          "description": "Whether the service supports suggestion of entities, in which case it should offer a /suggest/entity endpoint"
         },
         "property": {
-          "$ref": "#/properties/suggest/definitions/service_definition"
+          "type": "boolean",
+          "description": "Whether the service supports suggestion of properties, in which case it should offer a /suggest/property endpoint"
         },
         "type": {
-          "$ref": "#/properties/suggest/definitions/service_definition"
+          "type": "boolean",
+          "description": "Whether the service supports suggestion of types, in which case it should offer a /suggest/type endpoint"
         }
-      }
+      },
+      "required": [ "entity", "property", "type" ]
     },
     "preview": {
       "type": "object",
       "description": "Settings for the preview protocol, for HTML previews of entities",
       "properties": {
-        "url": {
-          "type": "string",
-          "pattern": ".*\\{.*id.*\\}.*",
-          "description": "A URL pattern which transforms the entity ID into a preview URL for it"
-        },
         "width": {
           "type": "integer",
           "description": "The width of the iframe where to include the HTML preview"
@@ -128,7 +106,6 @@
         }
       },
       "required": [
-        "url",
         "width",
         "height"
       ]
@@ -138,16 +115,8 @@
       "description": "Settings for the data extension protocol, to fetch property values",
       "properties": {
         "propose_properties": {
-          "type": "object",
-          "description": "Location of the endpoint to propose properties to fetch for a given type",
-          "properties": {
-            "service_url": {
-              "type": "string"
-            },
-            "service_path": {
-              "type": "string"
-            }
-          }
+          "type": "boolean",
+          "description": "Whether the service supports property proposals"
         },
         "property_settings": {
           "type": "array",