REST API basics
You can use the REST API to call Lingo3G clustering from non-Java languages. This article explains the basic REST API workflow.
Installation and running
Install Lingo3G on your machine.
Start the Lingo3G Document Clustering Server (DCS) application located in the
dcs/folder of your Lingo3G installation.
- On Windows, run the
- On Linux and Mac, run the
If the DCS starts successfully, you should see a terminal window with messages similar to the following:
16:59:55: DCS context initialized [algorithms: [Lingo3G], templates: [frontend-default]] 16:59:55: Service started on port 8080. 16:59:55: The following contexts are available: http://localhost:8080/ DCS Root http://localhost:8080/doc Documentation http://localhost:8080/frontend End-user apps http://localhost:8080/javadoc Java API Javadoc http://localhost:8080/service REST API
The DCS binds to port
8080by default. To select a different port, pass the
--portoption to the launch script, for example:
> dcs --port 8081
- On Windows, run the
Lingo3G REST API is available at the
/service URL prefix and
exposes the following endpoints:
- Clusters the documents you provide.
- Returns the list of clustering algorithms and languages the REST API supports.
Lingo3G REST API is stateless — the clustering results depend only on the contents of the documents you provide. This means, you can easily load-balance multiple DCS instances for redundancy and performance reasons.
The following sections show how to invoke Lingo3G clustering through the REST API. For detailed information and more examples, see the OpenAPI Swagger documentation (or alternatively RapiDoc, ReDoc, OpenAPI YAML).
Clusters the documents you provide. To invoke clustering, make a
POST request to the
endpoint with a JSON object like this:
The request JSON object can contain the following properties:
The language in which to perform clustering. Use
/listto get the list of supported languages.
The clustering algorithm to use, set to
Lingo3G parameter overrides. The object you provide must follow the Lingo3G parameters object structure. You can provide only the parameters you would like to customize.
You can export the parameters JSON object from Lingo3G Clustering Workbench.
An array of documents for clustering. Each array element must be an object representing one document. Each document can define one or more fields to cluster. Field names can be arbitrary, such as
body, values must be strings or arrays of strings.
Lingo3G clusters all of the document content you provide. If your data contains more fields for presentation purposes, exclude them from the clustering request.
See Documents for clustering for recommendations about the content you submit for clustering.
All properties of the request JSON are optional in the standard
configuration of Lingo3G DCS. The default value of
documents are empty. Therefore, the minimal meaningful
request can contain only the
documents array. To change the
request property defaults or create custom request templates, see
When making the request, you must set the
Content-Type header to
If clustering is successful, the response is a JSON object like this:
The response JSON has the following properties:
An array of top-level clusters. Each cluster has the following properties:
One or more labels describing the cluster.
An array of indices of documents in the cluster. Each element is a 0-based index of the document in the
documentsarray you provided in the clustering request.
An array of subclusters of this cluster. The array may be empty if there was not enough data to create a cluster hierarchy or you disabled hierarchical clustering.
The cluster's quality score. The score is not normalized in any way but represents relative quality of each cluster within this response.
The example JSON response contains two clusters:
Data Mining and Knowledge Discovery, each containing
two documents. Document
is present in both clusters.
To send a clustering request to the REST API running on localhost:8080
curl, use the following command:
Returns the list of supported clustering algorithm-language pairs. To
fetch the list, make a
GET request at the
endpoint. The JSON response is a JSON object like this:
Note that each algorithm has an associated list of language codes it
templates array lists the available
request templates .
If your software is Java-based, instead of the direct Lingo3G Java API, you may choose to call Lingo3G REST API from your Java code. In this case, instead of handling JSON creation and parsing by hand, you can use Lingo3G model classes like this:
You can serialize model instances into JSON using the
Jackson library. See
examples-dcs folder of Lingo3G distribution for complete
working examples of this approach.