Stanbol Home

The RESTful Semantic Engine

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*"):

Entityhub ("/entityhub"):


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 "http://demo2.fogbeam.org:8080/entityhub/entity?id=

Test

Get entity for URI

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} "http://demo2.fogbeam.org:8080/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} "http://demo2.fogbeam.org:8080/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} "http://demo2.fogbeam.org:8080/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} "http://demo2.fogbeam.org:8080/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} "http://demo2.fogbeam.org:8080/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} "http://demo2.fogbeam.org:8080/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:
  • the deleted entity encoded in the format specified by the Accept header
  • an empty response if all entities where deleted ('*' was parsed as URI
Status "404 NOT FOUND" if no Entity with the parsed URI is managed by the Entityhub

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.
  • If the parsed ID is a URI of a Symbol, than the stored information of the Symbol are returned in the requested media type ('accept' header field).
  • If the parsed ID is a URI of an already mapped entity, then the existing mapping is used to get the according Symbol.
  • If "create" is enabled, and the parsed URI is not already mapped to a Symbol, than all the currently active referenced sites are searched for an Entity with the parsed URI.
  • If the configuration of the referenced site allows to create new symbols, than a the entity is imported in the Entityhub, a new Symbol and EntityMapping is created and the newly created Symbol is returned.
  • In case the entity is not found (this also includes if the entity would be available via a referenced site, but create=false) a 404 "Not Found" is returned.
  • In case the entity is found on a referenced site, but the creation of a new Symbol is not allowed a 403 "Forbidden" is returned.
Request GET /lookup?id={uri}&create={create}
Parameter
  • id: the id of the entity
  • create: if "true" a new symbol is created if necessary and allowed
Produces Depends on requested media type

Example

curl "http://demo2.fogbeam.org:8080/entityhub/lookup/?id=http://dbpedia.org/resource/Paris&create=false"

Test


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
  • GET /entityhub/find?name={query}&field={field}&lang={lang}&limit={limit}&offset={offset}
  • POST -d "name={query}&field={field}&lang={lang}&limit={limit}&offset={offset}" /entityhub/find
Parameter
  • name: The name of the Entity to search. Supports '*' and '?'
  • field: The name of the field to search the name (optional, default is "http://www.iks-project.eu/ontology/rick/model/label").
  • language: The language of the parsed name (default: any)
  • limit: The maximum number of returned Entities (optional)
  • offset: The offset of the first returned Entity (default: 0)
  • select: A list of fields included for returned Entities (optional)
  • ldpath: The LDPath program executed for entities selected by the find query (optionally). The LDPath program needs to be URLEncoded.
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" http://demo2.fogbeam.org:8080/entityhub/sites/find

Test

Find entities with
Name: (required)
This supports Wildcards such as 'Exam?le*'
Language: (optional, default: any)
Field: (optional, reasonable default - usually rdfs:label)
Limit: (optional, number, default: 10) The maximum number of results
Offset: (optional, number, default: 0) The offset of the first returned result
LDPath:
(optional). LDPath programs can be used to specify what information to return for Entities selected by the /find request. This example selects the english labels, comments, categories, homepage and builds a string representing the location '[{latitude},{longitude}]'.
Output Format: (Accept header set to the request)


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" http://demo2.fogbeam.org:8080/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
  • GET /entityhub/ldpath?ldpath=ldpath&context={context1}[&context={contextn}]
  • POST -d "ldpath=ldpath&context={context1}[&context={contextn}]" /entityhub/ldpath
Parameter
  • ldpath: The LDPath program to execute.
  • context: The id of the entity used as context for the execution of the LDPath program. This parameter can occur multiple times
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" http://demo2.fogbeam.org:8080/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:

Context:
LD-Path:

Format: (Accept header set to the request)