SMILA/Documentation/Processing/JSON REST API for pipelets

JSON REST API for SMILA BPEL pipelets

SMILA now has an HTTP REST API that allows to display the registered pipelets as well as descriptions for single pipelets (i.e. class name, parameter description, pipelet description and other additional data) and even invoke them for test purposes.

Reference

Note: The trailing slash in URLs is optional.

Get Pipelet Overview

GET: Returns a list of all deployed pipelets which have been detected by the PipeletTracker including URLs to access their descriptions. The list also contains names of pipelets for which the pipelet description can be read from the SMILA-INF directory in the bundle, but the pipelet class cannot be successfully instantiated.

Supported operations:

• GET: Gets a list of all registered pipelets.

Usage:

• URL: http://<hostname>:8080/smila/pipelets/
• Allowed methods:
  • GET (no further URL parameters and no request body allowed)
• Response status codes:
  • 200 OK: Upon successful execution of GET.
  • 500 INTERNAL SERVER ERROR: Any other error.

Example:

GET http://localhost:8080/smila/pipelets/
200 OK
{
  "pipelets" : [{
    "class" : "org.eclipse.smila.processing.pipelets.xmlprocessing.RemoveElementFromXMLPipelet",
    "url" : "http://localhost:8080/smila/pipelets/org.eclipse.smila.processing.pipelets.xmlprocessing.RemoveElementFromXMLPipelet/"
  }, {
    "class" : "org.eclipse.smila.processing.pipelets.xmlprocessing.XPathFilterPipelet",
    "url" : "http://localhost:8080/smila/pipelets/org.eclipse.smila.processing.pipelets.xmlprocessing.XPathFilterPipelet/"
  }, {
    "class" : "org.eclipse.smila.processing.pipelets.xmlprocessing.XslTransformationPipelet",
    "url" : "http://localhost:8080/smila/pipelets/org.eclipse.smila.processing.pipelets.xmlprocessing.XslTransformationPipelet/"
  }, {
    "class" : "org.eclipse.smila.ontology.pipelets.SesameRecordReaderPipelet",
    "url" : "http://localhost:8080/smila/pipelets/org.eclipse.smila.ontology.pipelets.SesameRecordReaderPipelet/"
  }, {
    "class" : "org.eclipse.smila.tika.TikaPipelet,
    "url" : "http://localhost:8080/smila/pipelets/org.eclipse.smila.tika.TikaPipelet/"
  },
...
}

Get a Pipelet description

GET: Returns a JSON object containing the description of the requested pipelet. The object consists of the class name of the pipelet, optionally the textual description of the pipelet and the description of its parameters. Additionally to the original pipelet description read from the SMILA-INF of the bundle, the returned description can also contain errors if the pipelet class could not be instantiated (in this case the pipelet will not work properly in pipelines) or the pipelet description was not wellformed (in this case the pipelet should still work).

See [SMILA/Documentation/ParameterDefinition] for details on possible pipelet parameter descriptions.

Supported operations:

• GET: Get a pipelet description.

Usage:

• URL: http://<hostname>:8080/smila/pipelets/<pipelet-class-name>/
• Allowed methods:
  • GET (no further URL parameters and no request body allowed)
• Response status codes:
  • 200 OK: Upon successful execution for GET.
  • 404 NOT FOUND: If the specified pipelet does not exist.
  • 405 METHOD NOT ALLOWED: For methods other than "GET".
  • 500 INTERNAL SERVER ERROR: Any other error.

Example:

GET http://localhost:8080/smila/pipelets/org.eclipse.smila.processing.pipelets.CopyPipelet
200 OK
{
  "class" : "org.eclipse.smila.processing.pipelets.CopyPipelet",
  "parameters": [        
    {
      "name": "inputType",
      "type": "string",
      "values": ["ATTACHMENT", "ATTRIBUTE"]       
    },
    {
      "name": "outputType",
      "type": "string",
      "values": ["ATTACHMENT", "ATTRIBUTE"]         
    },
    {
      "name": "inputName",
      "type": "string"            
    },
    {
      "name": "outputName",
      "type": "string"            
    },
    {
      "name": "mode",
      "type": "string",
      "values": ["COPY", "MOVE"],
      "optional": true
    }     
  ],
  "description": "This pipelet can be used to copy a string value between attributes and/or attachments. 
It supports two execution modes: COPY: copy the value from the input attribute/attachment to the output 
attribute/attachment, MOVE: same as COPY, but after that delete the value from the input attribute/attachment"
}

Example with error messages

In this example the pipelet class did not exist in the bundle, and the parameter description was not valid. Both kinds of errors are listed under the errors key:

{
    "class":"org.eclipse.smila.processing.test.InvalidClassAndParametersPipelet",
    "parameters":[
        {
            "whats-this":"not-a-parameter"
        }
    ],
    "description":"test pipelet that won't be found and has invalid parameters description.",
    "errors":[
        "Pipelet class could not be loaded.",
        "Parameters section is invalid. Missing field 'name' or it has empty value."
    ]
}

Invoke a pipelet

POST: Creates an instance of the given pipelet and calls its process() method with the record contained in the request body. If the pipelet executes successfully and returns record IDs, the response body will contain the first result record (without attachments). If the record contains a map in key "_configuration" the configure() method is called with this map before the process() method. The pipelet instance is released after the call has finished.

This API is intended for testing purposes, not for usage in production environments.

Supported operations:

• POST: Invoke a pipelet

Usage:

• URL: http://<hostname>:8080/smila/pipelets/<pipelet-class-name>/process
• Allowed methods:
  • POST + JSON body
• Response status codes:
  • 200 OK: Upon successful execution for POST.
  • 400 BAD REQUEST: Pipelet does not exist or cannot be instantiated; configuration is invalid or other non-recoverable errors during execution
  • 405 METHOD NOT ALLOWED: For methods other than "POST".
  • 500 INTERNAL SERVER ERROR: Any other error.

Example:

POST http://localhost:8080/smila/pipelets/org.eclipse.smila.processing.pipelets.LanguageIdentifyPipelet/process
200 OK
{
  "_configuration": {
    "ContentAttribute": "Text",
    "LanguageAttribute": "Language"
  },
  "Text": "To be or not to be, that is the question"
}

==>

{
"_configuration": {
  "ContentAttribute": "Text",
  "LanguageAttribute": "Language"
},
"Text": "To be or not to be, that is the question",
"_recordid": "org.eclipse.smila.processing.pipelets.LanguageIdentifyPipelet-7cae7663-3aba-493d-9656-412e65af1d07",
"Language": "en"
}