Semantic Turkey HTTP Services

Semantic Turkey provides HTTP-based services for accessing all of its functionalities. These services can be used by those users needing some batch operations complementing the normal use of the application through its UI (e.g. Semantic Turkey Firefox client or VocBench), or by developers exploting the Semantic Turkey framework to power third-party applications.

The system has undergone diverse evolutions in these years: some of these required little changes to the service structure, which have been easily applied to the pre-existing services in order to align them to the new formats. In other cases, in order to keep working a large number of services which could not be easily adapted to the new specifications, we have often created wrappers for these old-fashioned services, enabling them to work even in new versions of the system.

Currently in Semantic Turkey (version 0.12 at the time of writing), there are three co-existing "generations" of services:

The set of core services of Semantic Turkey are all located in the st-core-services module of the project. The whole module is organized as an OSGi bundle and is not different from how a Semantic Turkey extension should look like. It can in fact be taken as an example for developing an extension.

Invoking the services

We currently have not devised an automatic system for publishing the documentation about the services, and we do not have the manpower for manually maintaining it. However there is a 1-1 direct relationship between the services code and their HTTP signature. While this might seem a trivial observation (well, indeed it is...), the good news is that this 1-1 relationship is quite explicit, and does not need deep diving into the code. Here we provide some information (and some) tricks for helping the interested user in understanding how to invoke the existing services.

Learning by Example

A good way to see actual http service calls in action is to use a client (e.g. the Firefox UI) and log the the calls made when each functionality is activated through interaction with the UI.

Inferring from Javascript docs and code

The Firefox Javascript apidocs provide a full list of all the services implemented in Semantic Turkey. This is a very easy-to-consult manual for at least understanding which services are available.

A further look inside the code will help, however parameter names in the javascript methods are not 100% guaranteed to be aligned with the actual http parameters needed by the service. Learn more here.

Note also that it is possible to learn by attempts: the javascript docs are at least reliable for understanding the services being invoked and thus their baseuri (see the description of the services in the next section). In order to understand the generation of the invoked services (to know the proper baseuri), it suffices to look at the preambles of their code and see if the STHttpMgrFactory object (for 2nd generation services) o SemTurkeyHTTPLegacy (for 1st generation) are being used. Invoking then a service with wrong or missing parameters will result in a error with a clear description of the missing parameters (at least of the mandatory ones).

Inferring from Javadocs and Java code

From the javadocs, it is immediately clear which service generation is being considered (see services description later). So it is possible to know the baseuri, and know (in the case of the 2nd and 3rd generation services) if the java parameter names are consistent with the http parameters of the http services.

Service Descriptions

We list here information for invoking services from these three generations.

Legacy Services (1st generation)

These services still represent the majority of the services currently published on the Semantic Turkey framework.

The 1st generation services are implemented through sets of java classes organized in OSGi bundles which can be hotplugged to the system. Each class represents a topic, collecting different logically coherent services under its umbrella. The handlers for the services are explicitly loaded into an OSGi registry and published onto a request dispatcher.

These services are all located in the it.uniroma2.art.semanticturkey.servlet.main package of the st-core-services module.

The URL shape for these services is the following:

  
  http://<domain>:<port>/semanticturkey/resources/stserver/STServer?service=<serviceClassID>&request=<serviceName>&<other parameters>

where:

The serviceClassID can be observed in the constructor of each service class. For instance, the class OntManager has the following constructor:


	@Autowired
	public OntManager(@Value("OntManager") String id) {
		super(id);
	}

where the ID is given by the string inside the @Value annotation ("OntManager" in this case)

The serviceName, and the number and name of the service parameters, can instead be easily derived by examinng the initial part of the service implementation code. All of 1st generation services are in fact preambled by a method called getPrecheckedResponse(String request), which implements an HTTP switch pattern in the following way:


	public Response getPreCheckedResponse(String request) throws HTTPParameterUnspecifiedException {
		this.fireServletEvent();
		if (request.equals(saveRDFRequest)) {
			String outPutFile = setHttpPar(filePar);
			boolean allNGs = setHttpBooleanPar(allNGsPar);
			checkRequestParametersAllNotNull(filePar);
			return saveRDF(new File(outPutFile), allNGs);
		}
		if (request.equals(loadRDFRequest)) {
			String inputFile = setHttpPar(filePar);
			String baseUri = setHttpPar(baseUriPar);
			String format = setHttpPar(formatPar);
			checkRequestParametersAllNotNull(filePar, baseUriPar);
			return loadRDF(new File(inputFile), baseUri, format);
		}
		if ...
        ...
        ...

		else
			return servletUtilities.createNoSuchHandlerExceptionResponse(request);

	}

which assigns the values of receveid http parameters to the parameters passed to the java implementations of the services, and re-routes the request to the proper method by comparing its associated serviceName with the request argument.

A sample request for the Projects class and the listProjects service is the following:

http://127.0.0.1:1979/semanticturkey/resources/stserver/STServer?service=projects&request=listProjects

Current Services (2nd generation)

The development of these services was made possible by the introduction of the Spring Framework inside the ST architecture and by using features of the Aspect Programming paradigm. These services are java-annotated as ST-Services, and are automatically published on the OSGi registry by the controlling framework. The typical dualistic nature of service/controllers has been overcome by assuming that the controller follow pre-defined mapping procedures and conventions. So there is no code for controllers which is manually produced, it is instead automatically generated by a Velocity script. The build-time generation of controllers' code allowed us to keep the names of the java parameters declared in the Java methods signatures consistent with the names adopted in their HTTP counterpart, by re-writing them in the mappings declared in the generated service controllers.

These services are all located in the it.uniroma2.art.semanticturkey.services.core package of the st-core-services module.

The URL shape for these services follows this pattern:

http://<domain>:<port>/semanticturkey/<groupId>/<artifactId>/<ClassName>/<methodName>?<parameters>

where:

For those not familiar with Maven, the POM (project object model) is implemented in the pom.xml file at the root of the sources (there is one general pom.xml for the whole project, and one pom.xml for each module)

So, for instance, the core services, being hosted in the st-core-services module of Semantic Turkey, which has the following POM, have the following information:

groupID = it.uniroma2.art.semanticturkey (inherited from the parent project)
artifactID = st-core-services

and a sample request (same service of the 1st generation example) is:

http://127.0.0.1:1979/semanticturkey/it.uniroma2.art.semanticturkey/st-core-services/Projects/listProjects

New Services (3rd generation)

The third generation of services is under active development. They will be part of a major evolution of the Semantic Turkey framework. Currently, they are located in the it.uniroma2.art.semanticturkey.services.core package of the st-core-services module, together with the 2nd generation services.

Unless further changes are imposed, their URL shape is the same of the 2nd generation services.

Currently, these services are being implemented in versions of Semantic Turkey following 0.12

Example batches and PHP code for using ST HTTP services

Philippe Clastre (INRA) contributed the following two examples, taken from the batches he uses to extract information from a Semantic Turkey (v 0.12) server powering a VocBench 2.4.1 instance. The version of PHP being used is 5.6.

An example of a sparql query using bash (unix) and the CURL command

The following commands can be ran in a unix shell. It gives the user the opportunity to check if a specific term exists in the thesaurus.


baseurl="http://123.456.789.000:1979/semanticturkey/resources/stserver/STServer"
project="my_thesaurus"
curl -v -d service=sparql -d request=resolveQuery -d ctx_project=$project --data-urlencode query@sparql_query.txt $baseurl

The parameter query@sparql_query.txt defines the name of a file (sparql_query.txt) that will contain the query itself. This avoids very long command line …

The output of the query is displayed after the command line.

An example of a sparql query using php and curl function

The following php code can be used in an apache environment. The proposed query returns the preflabel of a concept if you give one altlabel. 


  //define a sparql query

  $query='PREFIX skos: <http://www.w3.org/2004/02/skos/core#> 

  PREFIX skosxl: <http://www.w3.org/2008/05/skos-xl#> 

  select distinct ?otherLiteralForm where { 

  ?c a skos:Concept . 

  ?c skosxl:altLabel ?xl . 

  ?xl skosxl:literalForm ?lxl. 

  ?c skosxl:prefLabel ?otherxl . 

  ?otherxl skosxl:literalForm ?otherLiteralForm. 

  FILTER (regex(?lxl,"^XXXX$","i")&& 

  langMatches(lang(?otherLiteralForm), "en"))}';
  //define the name of the thesaurus

  $project=’my_thesaurus’;
  //define the default URL to contact

  $url=’http://localhost:1979/’
  //create a array with curl options/parameters

  post = array( 

  'service' => 'sparql', 

  'request' => 'resolveQuery', 

  'ctx_project' => $project, 

  'query' => $query , 

  );
  //open curl access

  $ch=curl_init() or die('Error on curl init');
  //load curl parameters with previously defined php variables

  curl_setopt($ch, CURLOPT_URL, $url); 

  curl_setopt($ch, CURLOPT_POST, count($post)); 

  curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($post)); 

  curl_setopt($ch, CURLOPT_RETURNTRANSFER,true);
  //execute the query 

  $result = curl_exec($ch);

  //$result is an xml text and can be parsed with specific XML library 

  //(simpleXML …)
  //close curl access

  curl_close($ch);