Use cases

REST API request templates can be useful in the following situations:

• To detach the clustering algorithm configuration from the code that makes clustering requests. In this arrangement, the request JSON contains only the documents for clustering and the template provides the remaining configuration.

• To create aliases for differently tuned versions of Lingo3G. For example, you can create a template called focused that changes a number of parameters to make clusters more specific.

Creating request templates

To create a request template, perform these steps:

1. Create a file called, for example, 01 focused.json in the dcs/web/service/templates/ directory of your Lingo3G installation.

   The focused part of the file name is the identifier of the template. The 01 number at the front is not part of the identifier, it is used to sort templates for display purposes.

2. Edit the template file to contain a JSON object with the same structure as the clustering request JSON.

   For example, a template for creating more specific clusters can contain the following:

   {
     "language": "English",
     "algorithm": "Lingo3G",
     "parameters": {
       "clusters": {
         "maxClusterSize": 0.2
       },
       "hierarchy": {
         "maxClusteringPassesTop": 0
       },
       "labels": {
         "singleWordLabelWeight": 0.2
       }
     }
   }

3. Restart Lingo3G DCS to make the new template available for clustering.

4. (Optional) Verify that the new template is present by making a GET request to the /list endpoint. The response should contain the following section:

   ...
     "templates" : [
       "frontend-default",
       "foo"
     ]
   }

Using request templates

To use a template for a clustering request, pass the template identifier in the template query parameter of the /cluster endpoint:

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

The request JSON you submit can now contain only the document list, the template provides the remaining parts:

{
  "documents": [
    {
      "title": "Data Mining in Python",
      "content": "Collection of libraries for machine learning."
    },
    {
      "title" : "KDD Lab: knowledge discovery from large spatial data."
    },
    {
      "title": "Data Mining",
      "snippet": [
        "Data mining uses machine learning ...",
        "... automated knowledge discovery tools."
      ]
    }
  ]
}

If you provide other parts in your request JSON too, they will override the configuration from the template. For example, you can change the clustering language by providing a new language name:

{
  "language": "German",
  "documents": [
    {
      "title": "Was ist Data Mining? ",
      "content": "Data Mining ist die systematische Anwendung ..."
    },
    {
      "title" : "Das Dilemma mit den sozialen Medien."
    },
    {
      "title": "Kollaboratives Filtern",
      "snippet": [
        "Interessen Einzelner zu schließen."
      ]
    }
  ]
}