Entityhub
Service Endpoints
The Entityhub provide two main service. First it allows to manage a network of site used to consume Entity Information from and second it allows to manage locally used Entities.
The RESTful API of the Entityhub ist structured as follows.
Entity Network ("/entityhub/site*"):
- Referenced Site Manager @ /entityhub/sites: Manages the network of Referenced Sites and allows to retrieve and search Entities in all Sites of the Entity Network.
- Referenced Site @
/entityhub/site/{siteName}: A single Site of the Referenced Site Manager allows to retrieve all active Sites. Referenced Sites provide the same Interface as the Referenced Site Manager.
Currently active Referenced Sites:
Entityhub ("/entityhub"):
- Local Entities @/entityhub/entity: Full CRUD operations on Entities managed by the Entityhub
- Entity Mappings @ /entityhub/mapping: Lookup mappings from local Entities to Entities managed by a Referenced Site
- Local Search @/entityhub/find: Find locally managed Entities by label based search.
- Local Query @/entityhub/query: Find locally managed Entities by parsing queries
- Entity Lookup @/entityhub/lookup: Lookup Entities by id. This supports also to lookup Entities managed by Referenced Sites and the import of found Entities to the Entityhub.
- LDPath @/entityhub/ldpath: Allows to execute LDPath programs on locally managed Entities.
- Reconciliation @/entityhub/reconcile: Implements the Google Refine Reconciliation API
Subresource entityhub/entity
Service to get/create/update and delete Entities managed by the Entityhub.
GET entityhub/entity
| Description | Service to get |
|---|---|
| Request | GET /entityhub/entity?id={uri} |
| Parameter | id: the URI of the entity |
| Produces | Depends on requested media type |
Example
curl "https://enrich.acdh.oeaw.ac.at/entityhub/entity?id=
Test
Create an Entity
| Description | Service to create entities for the Entityhub. |
|---|---|
| Request | POST /entityhub/entity?[id={uri}]&[update=true/false] |
| Parameter | id: optional the id of the Entity to add. If an id is parsed it is
ensured that regardless of the included data only the entity with the
parsed id is created. Information for other ids will be ignored. update: Switch that allows to allow updates to existing entities for POST requests. Default is false
|
| Produces | 201 with an link to the created entity |
Examples:
The following request would create all Entities defines within {file.rdf} in the entityhub. If any of such Entities already exists within the Entityhub the request would fail with BAD REQUEST
curl -i -X POST -H "Content-Type:application/rdf+xml" -T {file.rdf} "https://enrich.acdh.oeaw.ac.at/entityhub/entity
Here the same request, but now it would be also allowed to update existing Entities
curl -i -X POST -H "Content-Type:application/rdf+xml" -T {file.rdf} "https://enrich.acdh.oeaw.ac.at/entityhub/entity?update=true
This request would only import the Entity with the id {id} while ignoring all triples with a subject other that {id} contained within {file.rdf}
curl -i -X POST -H "Content-Type:application/rdf+xml" -T {file.rdf} "https://enrich.acdh.oeaw.ac.at/entityhub/entity?id={id}
Update an Entity
| Description | Service to update an Entity already managed by the Entityhub | |
|---|---|---|
| Request | PUT /entityhub/entity?[id={uri}]&[create=true/false] | |
| Parameter | id: optional the id of the Entity to update. If an id is parsed it is
ensured that regardless of the parsed data only information of this entity
are updated. create: Switch that allows to enable/disable the creation of new Entities for update (PUT) requests. The default true.
|
|
| Produces | 200 with the data of the entity encoded in the format specified by the Accept header |
Examples:
The following request would update/create all Entities defines within {file.rdf} in the entityhub. Non existent Entities will be created and already existing one will be updated (replaced with the submitted version).
curl -i -X PUT -H "Content-Type:application/rdf+xml" -T {file.rdf} "https://enrich.acdh.oeaw.ac.at/entityhub/entity
This request would only update Entities. If any of the Entities in {file.rdf} would not already be present within the Entityhub this request would return a BAD REQUEST.
curl -i -X PUT -H "Content-Type:application/rdf+xml" -T {file.rdf} "https://enrich.acdh.oeaw.ac.at/entityhub/entity?create=false
This request would update the Entity with the id {id} while ignoring all triples with a subject other that {id} contained within {file}. If an entity with {id} is not yet present within the Entityhub, than a BAD REQUEST would be returned
curl -i -X POST -H "Content-Type:application/rdf+xml" -T {file.rdf} "https://enrich.acdh.oeaw.ac.at/entityhub/entity?id={id}&create=false
Delete an/all Entities
| Description | Service to delete an/all entities managed by the Entityhub |
|---|---|
| Request | DELETE /entityhub/entity?id={uri} |
| Parameter | id: The {uri} of the Entity to delete or '*' to delete all Entities |
| Produces |
Status "200 OK" with:
|
Subresource /lookup?id={uri}&create={create}
| Description | This service looks-up Symbols (Entities managed by the Entityhub) based on the parsed URI. The
parsed ID can be the URI of a Symbol or an Entity of any referenced site.
|
|---|---|
| Request | GET /lookup?id={uri}&create={create} |
| Parameter |
|
| Produces | Depends on requested media type |
Example
curl "https://enrich.acdh.oeaw.ac.at/entityhub/lookup/?id=http://dbpedia.org/resource/Paris&create=false"
Test
- Lookup symbol for entity 'http://dbpedia.org/resource/Paris' with create=false.
- Lookup symbol for entity 'http://dbpedia.org/resource/Paris' with create=true.
Subresource /entity/find?name={name}
| Description | This service can be used to search for Entities in the Entityhub. Both a POST and a GET version are available. |
|---|---|
| Request |
|
| Parameter |
|
| Produces | Depends on requested media type |
Example
The following query would search for Entities with a 'rdfs:label' that starts with 'Pari'.
curl -X POST -d "name=Pari*&field=http://www.w3.org/2000/01/rdf-schema#label" https://enrich.acdh.oeaw.ac.at/entityhub/sites/find
Test
Subresource /query
| Description | Allows to parse JSON serialized field queries to the Entityhub. Only Entities managed by the Emtityhub are searched |
|---|---|
| Request | -X POST -H "Content-Type:application/json" --data "@fieldQuery.json" /entityhub/query |
| Parameter | The JSON serialised FieldQuery |
| Produces | The results of the query serialised in the format as specified by the Accept header |
Example
curl -X POST -H "Content-Type:application/json" --data "@fieldQuery.json" https://enrich.acdh.oeaw.ac.at/entityhub/query
Note: "@fieldQuery.json" links to a local file that contains the parsed Fieldquery (see ection "FieldQuery JSON format" for examples).
Subresource /ldpath (/ldpath?ldpath={ldpath}&context={context})
| Description | This service can be used to execute an LDPath program on one or more Entities (contexts). Both a POST and a GET version are available. |
|---|---|
| Request |
|
| Parameter |
|
| Produces: | Produces an RDF Graph with the parsed context(s) as subject the field selected by the LDPath program as properties and the selected values as object. All RDF serialisations are supported however JSON-LD seams to be a natural fit for the data created by LDPath. JSON-LD is also the default encoding. |
Example
The following LDPath statement will be executed on the defined contexts
curl -X POST -d "context=http://dbpedia.org/resource/Paris&ldpath=name%20%3D%20rdfs%3Alabel%5B%40en%5D%3B" https://enrich.acdh.oeaw.ac.at/entityhub/ldpath
NOTE: the LDPath MUST BE URLEncoded. The decoded string of the above example is "name = rdfs:label[@en];" and would select the english label of Paris in the field "name".
Test
Execute the LDPath on the Context:
