Custom Services


Custom Services provide a means to extend ShowVoc at the service-layer by enabling the definition of new services in a rather high-level manner. It is sufficient to have a general understanding of the conceptual model of the services (i.e. how they are composed), and the ability to express the desired behavior in some implementation language, currently, only SPARQL queries and updates. Custom services relieve the user from the need to know the underlying architecture of ShowVoc, the use of OSGi to support extendability, or the underlying programming model used to write services. Furthermore, there is no longer any need to set up a separate development environment, since all development is done within ShowVoc itself.

Conceptual Model

A Custom Service groups a number of related operations under a unique service name. Operations define the actual behavior of the service. Each operation is identified by a name (which shall be unique within a custom service), zero or more (formal) parameters, a return type and an authorization string. The actual behavior associated with the operation is defined by means of additional information specified by the chosen CustomServiceBackend: currently, there is only backend supporting the specification of an operation through a SPARQL query (for read services) or a SPARQL update (for mutation services).

The operations defined by a custom service can be invoked by issuing a GET (for read services) or a POST (for mutation services) to addresses matching the following pattern:


Editing Custom Services

The following figure depicts the main user interface for editing custom services. The page can be accessed by authorized users through the Custom Services and Reports item under Tools menu.

The panel on the left lists the available custom services, providing buttons to create a new service, delete an existing one, and refresh the list. The dropdown menu associated with the refresh button offers the option to force reload the services the file system. This option is only useful if custom services are edited outside of ShowVoc, by editing the underlying representation on the file system. The items of the list are the service identifiers of the custom services. Under the hood, these identifiers identify configurations used to persist the definition of custom services in the configuration manager

The panel on the right shows the specification of any custom service that has been selected in the list on the left. The specification consists of a service name, description and a list of operations. The button labeled with a pencil near the first two fields can be used to edit the corresponding values. The list of operations is associated with buttons to create a new operation and delete an existing operation. The combined refresh button in the header of the right panel behaves like the already mentioned button, but limited to the currently selected service.

After selecting an operation, the user interface is extended with a further panel showing its details, as depicted by the figure below.

Defining the operation authorization

The authorization string associated with an operation is used to determine whether an invocation of the operation should be allowed or forbidden (based on the user doing the invocation).

The authorization string consists of three parts:

If no authorization is provided, the following defaults apply:

The screenshot below depicts the wizard for the definition of an authorization string.

Defining Custom Services Operations in SPARQL

The parameters are mapped to variables with the same name in the SPARQL query. Actual parameters passed to a service upon invocation are pre-bound to the corresponding variable in the SPARQL query. A reserved variable is workingGraph, which is bound by default to the working graph of the project.

The allowed parameter types are:

The allowed return type depends on the actual SPARQL operation: