{"componentChunkName":"component---node-modules-carrotsearch-gatsby-theme-apidocs-templates-documentation-page-js","path":"/rest-api-basics/","result":{"data":{"html":{"frontmatter":{"id":"rest-api-basics","title":"REST API basics"},"html":"
\n

REST API basics

\n\n

\n You can use the REST API to call Lingo3G clustering from non-Java languages.\n This article explains the basic REST API workflow.\n

\n\n
\n

\n Installation and running\n

\n\n
    \n
  1. \n

    \n Install Lingo3G on your\n machine.\n

    \n
    2. \n\n
  2. \n

    \n Start the\n Lingo3G Document Clustering Server (DCS)\n application located in the dcs/\n folder of your Lingo3G installation.\n

    \n\n
      \n
    • On Windows, run the dcs.cmd script.
      • \n
    • On Linux and Mac, run the dcs script.
      • \n
    \n\n

    \n If the DCS starts successfully, you should see a terminal window with\n messages similar to the following:\n

    \n\n
    \n 
    16:59:55: DCS context initialized [algorithms: [Lingo3G], templates: [frontend-default]]\n16:59:55: Service started on port 8080.\n16:59:55: The following contexts are available:\n  http://localhost:8080/          DCS Root\n  http://localhost:8080/doc       Documentation\n  http://localhost:8080/frontend  End-user apps\n  http://localhost:8080/javadoc   Java API Javadoc\n  http://localhost:8080/service   REST API
    \n
    \n\n

    \n The DCS binds to port 8080 by default. To select a\n different port, pass the --port\n option to the launch script, for example:\n

    \n\n
    \n 
    > dcs --port 8081
    \n
    \n
    3. \n
\n
\n\n
\n

\n REST endpoints\n

\n\n

\n Lingo3G REST API is available at the /service URL prefix and\n exposes the following endpoints:\n

\n\n
\n
\n /cluster\n
\n
Clusters the documents you provide.
\n\n
\n /list\n
\n
\n Returns the list of clustering algorithms and languages the REST API\n supports.\n
\n
\n\n

\n Lingo3G REST API is stateless — the clustering results\n depend only on the contents of the documents you provide. This means, you\n can easily load-balance multiple DCS instances for redundancy and\n performance reasons.\n

\n\n

\n The following sections show how to invoke Lingo3G clustering through the\n REST API. For detailed information and more examples, see the\n OpenAPI Swagger documentation\n (or alternatively\n RapiDoc,\n ReDoc,\n OpenAPI YAML).\n

\n\n
\n

\n /cluster\n

\n\n

\n Clusters the documents you provide. To invoke clustering, make a\n POST request to the /cluster\n endpoint with a JSON object like this:\n

\n\n
\n
\n 
POST /service/cluster HTTP/1.1\nHost: localhost:8080\nContent-Type: text/json\n\n{\n  \"language\": \"English\",\n  \"algorithm\": \"Lingo3G\",\n  \"parameters\": {\n    \"clusters\": {\n      \"maxClusterSize\": 0.8\n    }\n  },\n  \"documents\": [\n    {\n      \"title\": \"Data Mining in Python\",\n      \"content\": \"Collection of libraries for machine learning.\"\n    },\n    {\n      \"title\" : \"KDD Lab: knowledge discovery from large spatial data.\"\n    },\n    {\n      \"title\": \"Data Mining\",\n      \"snippet\": [\n        \"Data mining uses machine learning ...\",\n        \"... automated knowledge discovery tools.\"\n      ]\n    }\n  ]\n}
\n
\n
\n

Example /cluster request headers and body.

\n
\n
\n\n

The request JSON object can contain the following properties:

\n\n
\n
language
\n
\n

\n The language in which to perform clustering. Use/list\n to get the list of supported languages.\n

\n
\n\n
algorithm
\n
\n

The clustering algorithm to use, set to Lingo3G.

\n
\n\n
parameters
\n
\n

\n Lingo3G parameter overrides. The object you provide must follow the\n Lingo3G parameters object\n structure. You can provide only the parameters you would like to\n customize.\n

\n\n

\n You can\n export the parameters JSON\n object from Lingo3G Clustering Workbench.\n

\n
\n\n
documents
\n
\n

\n An array of documents for clustering. Each array element must be an\n object representing one document. Each document can define one or\n more fields to cluster. Field names can be arbitrary, such as\n title or body, values must be strings or\n arrays of strings.\n

\n\n

\n Lingo3G clusters all of the document content you provide. If your\n data contains more fields for presentation purposes, exclude them\n from the clustering request.\n

\n\n

\n See\n Documents for clustering\n for recommendations about the content you submit for clustering.\n

\n
\n
\n\n

\n All properties of the request JSON are optional in the standard\n configuration of Lingo3G DCS. The default value of\n language is English, algorithm is\n Lingo3G and parameters and\n documents are empty. Therefore, the minimal meaningful\n request can contain only the documents array. To change the\n request property defaults or create custom request templates, see\n Request templates.\n

\n\n

\n When making the request, you must set the\n Content-Type header to text/json.\n

\n\n

\n If clustering is successful, the response is a JSON object like this:\n

\n\n
\n
\n 
{\n  \"clusters\" : [\n    {\n      \"labels\" : [\n        \"Data Mining\"\n      ],\n      \"documents\" : [\n        0,\n        2\n      ],\n      \"clusters\" : [ ],\n      \"score\" : 1.0\n    },\n    {\n      \"labels\" : [\n        \"Knowledge Discovery\"\n      ],\n      \"documents\" : [\n        1,\n        2\n      ],\n      \"clusters\" : [ ],\n      \"score\" : 0.9829125404836723\n    }\n  ]\n}
\n
\n\n
\n

Example /cluster response.

\n
\n
\n\n

The response JSON has the following properties:

\n\n
\n
clusters
\n
\n

\n An array of top-level\n clusters. Each cluster\n has the following properties:\n

\n\n
\n
labels
\n
\n

One or more labels describing the cluster.

\n
\n\n
documents
\n
\n

\n An array of indices of documents in the cluster. Each element is\n a 0-based index of the document in the\n documents\n array you provided in the clustering request.\n

\n
\n\n
clusters
\n
\n

\n An array of subclusters of this cluster. The array may be empty\n if there was not enough data to create a cluster hierarchy or\n you disabled\n hierarchical\n clustering.\n

\n
\n\n
score
\n
\n

\n The cluster's quality score. The score is not normalized in any\n way but represents relative quality of each cluster within this\n response.\n

\n
\n
\n
\n
\n\n

\n The example JSON response contains two clusters:\n Data Mining and Knowledge Discovery, each containing\n two documents. Document 2\n is present in both clusters.\n

\n\n

\n To send a clustering request to the REST API running on localhost:8080\n with\n curl, use the following command:\n

\n\n
\n
\n 
curl -X POST --header \"Content-Type: text/json\" --data-binary @cluster-request.json \"http://localhost:8080/service/cluster?indent\"
\n
\n\n
\n

Calling REST API using curl.

\n
\n
\n
\n\n
\n

\n /list\n

\n\n

\n Returns the list of supported clustering algorithm-language pairs. To\n fetch the list, make a GET request at the\n /list\n endpoint. The JSON response is a JSON object like this:\n

\n\n
\n
\n 
{\n  \"algorithms\" : {\n    \"Lingo3G\" : [\n      \"Dutch\",\n      \"English\"\n    ]\n  },\n  \"templates\" : [\n    \"frontend-default\"\n  ]\n}
\n
\n\n
\n

Example /list response.

\n
\n
\n\n

\n Note that each algorithm has an associated list of language codes it\n supports. The templates array lists the available\n request templates .\n

\n
\n
\n\n
\n

\n Java models\n

\n\n

\n If your software is Java-based, instead of the direct\n Lingo3G Java API, you may\n choose\n to call Lingo3G REST API from your Java code. In this case, instead of\n handling JSON creation and parsing by hand, you can use Lingo3G model\n classes like this:\n

\n\n
\n
\n 
Lingo3GClusteringAlgorithm algorithm = new Lingo3GClusteringAlgorithm();\nalgorithm.clusters.maxClusterSize.set(1.0);\n\nClusterRequest request = new ClusterRequest();\nrequest.algorithm = Lingo3GClusteringAlgorithm.NAME;\nrequest.language = \"English\";\nrequest.parameters = Attrs.extract(algorithm);\nrequest.documents =\n    Stream.of(\n            \"Data Mining in Python\",\n            \"Knowledge Discovery and Data Mining Lab\",\n            \"Knowledge Discovery tools\")\n        .map(\n            value -> {\n              ClusterRequest.Document doc = new ClusterRequest.Document();\n              doc.setField(\"title\", value);\n              return doc;\n            })\n        .collect(Collectors.toList());
\n
\n\n
\n

Using Java model classes to build Lingo3G REST API request JSONs.

\n
\n
\n\n

\n You can serialize model instances into JSON using the\n Jackson library. See\n the examples-dcs folder of Lingo3G distribution for complete\n working examples of this approach.\n

\n
\n
","tableOfContents":[{"heading":"Installation and running","anchor":"installation"},{"heading":"REST endpoints","anchor":"rest-endpoints","sections":[{"heading":"/cluster","anchor":"/cluster"},{"heading":"/list","anchor":"/list"}]},{"heading":"Java models","anchor":"java-models"}]}},"pageContext":{"slug":"/rest-api-basics/"}},"staticQueryHashes":["1164750013"]}