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 66c5730..b1bc87d 100644 --- a/latest/index.html +++ b/latest/index.html @@ -190,9 +190,11 @@- No changes made yet. -
+Collection of changes which make the API conform to the REST principles.
+versions which is about the versions of the reconciliation API supported by the service;viewurl. Its value is a URI template for entities;feature_view
+ feature_viewurl. Its value is a URI template for matching features;previewsuggestentitypropertytypeextend
+ 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 /.
+
+
//reconcile/suggest/entity/suggest/property/suggest/type/preview/extend/extend/propose@@ -554,27 +582,15 @@
- A reconciliation service MUST support HTTP POST requests on its endpoint with
- application/x-www-form-urlencoded bodies containing a
+ 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 (serialized in JSON) in a form element named queries.
-
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.
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:
urlid 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<iframe> element where to render an entity preview;heightA 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 iframe HTML element 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:
@@ -655,28 +669,18 @@ - 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_urlservice_pathservice_url to obtain the full URL of the suggest service;flyout_service_urlservice_url;flyout_service_pathflyout_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 athttps://example.com/api/suggest with an associated flyout endpoint at https://example.com/api/suggest/flyout/${id}.
-
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.
- 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:
-
idhtml
- 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.
-
extend field. It consists of the following settings, all optional:
propose_propertiesservice_urlservice_pathproperty_settings- 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: @@ -869,19 +834,11 @@
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",