Rest

Rest-API #

This page contains an overview of basic information and usage of the ProCAKE-Rest project.

Basic Information #

The ProCAKE-Rest API provides a basic interface for interacting and configuring a running CAKE-Instance. According to the RESTful Design-Pattern, it allows for manipulation of ProCAKE resources via simple GET, PUT and DELETE operations. For this purpose, there are several endpoints available that can be addressed via simple HTTP requests (synchronous and asynchronous). Endpoints can be accessed by navigating over the root context as follows:

http://{hostAddress:port}/api/endpoint

In order to get a quick overview of existing endpoints and their behavior at glance, the swagger documentation is served upon server startup at

http://{hostAddress:port}

A static version of the documentation can be found here.

Endpoints #

There are several endpoints available for retrieving basic information about the current CAKE-Instance and performing modifications and retrievals on CaseBases. While administration-oriented endpoints (e.g. Configuration) require advanced user roles, a guest-role will be sufficient in order to access these usage-related endpoints (Basic-Authentication).

Info #

The Information-Endpoint provides an overview of DataClasses, SimilarityMeasures and ObjectPools currently registered in the running CAKE-Instance, as well as a status report that indicates whether the current instance was properly started or not. Depending on the Accept-Type Header of the HTTP Request, the Information-Endpoint servers both XML and JSON response-types.

http://{hostAddress:port}/api/info/classes  @GET
http://{hostAddress:port}/api/info/measures @GET
http://{hostAddress:port}/api/info/pools    @GET
http://{hostAddress:port}/api/info/status   @GET

CaseBase #

The CaseBase-Endpoint enables the insertion, replacement and deletion of CaseBases and Cases within the running CAKE-Instance. Modifying calls such as insertion and replacement of CaseBases/Cases do not deliver response content. Upon deletion, the deleted CaseBase/Case is returned as an XML response-type. Unlike the Information-Endpoint, the CaseBase-Endpoint requires use of PUT and DELETE operations, so HTTP request bodies should be designed accordingly (see Usage). In general, the API is designed to accept ProCAKE object-structures in XML representation, in alignment with ProCAKE internal ObjectParser and ObjectPoolParser.

For a detailed overview of available endpoints and their expected format and parameter types, as well as response codes/types, please refer to the Swagger documentation.

http://{hostAddress:port}/api/cases/{caseBaseID} @GET (Fetch)
http://{hostAddress:port}/api/cases/{caseBaseID} @PUT (Add/Replace)
http://{hostAddress:port}/api/cases/{caseBaseID} @DELETE (Remove)

http://{hostAddress:port}/api/cases/{caseBaseID}/{caseID} @GET (Fetch)
http://{hostAddress:port}/api/cases/{caseBaseID}/{caseID} @PUT (Add/Replace)
http://{hostAddress:port}/api/cases/{caseBaseID}/{caseID} @DELETE (Remove)

Textual Retrieval #

The Retrieval-Endpoint facilitates basic retrieval queries within ProCAKE. While retrival/info provides a list of available retrievers, the actual query is performed addressing textual/retrieval/{retrieverID}/{CaseBaseID}. It is worth noting that all retriever-specific configuration is done via HTTP Query-Parameter. If those parameters are not set, ProCAKE default values will be used to perform the query. The Query-Parameters setSorting and setTaskSize are specific to the ParallelLinearRetriever and can be ignored when using a different retriever. Similar to previously discussed endpoints, the Retrieval-Endpoint expects the query-object to be passed in XML representation.

http://{hostAddress:port}/api/retrival/info @GET
http://{hostAddress:port}/api/retrieval/textual/{retrieverID}/{caseBaseID}?numberOfResults={numberOfResults}&setSorting={sorting}&setTaskSize={taskSize} @PUT

Object-based Retrieval #

For the sake of tight integration with ProCAKE-internal objects and working with retrieval-specific data, retrieval can also be performed passing a Query-object directly to the server, which will trigger a response containing a serialized RetrievalResultList. In order to pass these objects, both offer toXML() and fromXML() methods, that allow for simple serialization and deserialization. A new Query-Parameter addQueryToResults was introduced, which can be used to include the Query-object in the returned RetrievalResultList.

http://{hostAddress:port}/{rootContext}/api/retrieval/{retrieverID}/{caseBaseID}?addQueryToResults={addQueryToResults}&setSorting={sorting}&setTaskSize={taskSize} @PUT

Conversion #

The Conversion-Endpoint provides utility functionalities for internal conversion of models and data structures. Currently, available converters are:

  • BPMNtoNEST
  • OldModelConverter
  • OldSimilarityModelConverter

The list of available converters can also be retrieved via conversion/info. In accordance with the other endpoints, converters expect the query-object to be passes in XML representation withing the HTTP request body.

http://{hostAddress:port}/api/conversion/info           @GET
http://{hostAddress:port}/api/conversion/{converterID}  @PUT

Administration #

This section deals with configuration that goes beyond the basic usage of the API, such as manipulation of DataClass and SimilarityMeasure Models and management of users and their privileges. Also, it provides an overview of how to set up a custom CAKE-configuration to be served by the API.

Configuration #

The Configuration-Endpoint allows for manipulation of DataClasses and SimilarityMeasures at runtime of the CAKE-Instance. Accessing this resource requires ADMIN privileges (see User Roles). Since the API uses JAXB XML-Mapping, the insertion of classes and measures has to follow a strict structure in order to be mappable to predefined POJOs. For instance, the XML-representation of a new DataClass named myClass that inherits from String should look like the following:

<?xml version="1.0" encoding="UTF-8"?>
<DataClassModel>
	<name>myClass</name>
	<superClass>String</superClass>
</DataClassModel>

Similarly, a new SimilarityMeasure, in this case a new StringNGramMeasure myMeasure, should look this:

<?xml version="1.0" encoding="UTF-8"?>
<SMStringNGram>
	<name>myMeasure</name>
	<dataClass>String</dataClass>
	<caseSensitive>true</caseSensitive>
	<size>5</size>
</SMStringNGram>

For a detailed overview of available measure-models and their specific configurable parameters, please refer to the Swagger documentation. The creation of new classes and measures does not deliver response content. The deletion of such however will return an XML or JSON response-type of the deleted class/measure, depending on the request header.

http://{hostAddress:port}/api/configuration/dataclass   @PUT
http://{hostAddress:port}/api/configuration/{className} @DELETE

http://{hostAddress:port}/api/configuration/similarityMeasure/StringEqual       @PUT
http://{hostAddress:port}/api/configuration/similarityMeasure/StringNGram       @PUT
http://{hostAddress:port}/api/configuration/similarityMeasure/StringLevenshtein @PUT
...

User Roles #

The current implementation of the API provides for Basic-Authentication in order to access the endpoints. User roles can be edited and granted to user within the in-memory integrated H2-database. For this purpose, the application executes a basic SQL-Script on startup:

INSERT INTO userAuth(username, password, role) VALUES('Maxim', '1234', 'ADMIN');
INSERT INTO userAuth(username, password, role) VALUES('Peter', 'abcd', 'DEVELOPER');

If needed, this script can be accessed at .../resources/sql/data.sql. In order to set or modify roles for specific resource methods, they can simply be annotated with @RolesAllowed({"roleA","roleB"}) while roles correspond to the ones set in the database.