Difference between revisions of "SMILA/Documentation/Processing/JSON REST API for BPEL pipelines"

Revision as of 03:29, 18 May 2011

Processing JSON REST API

New in 0.9

SMILA now has a HTTP REST API that allows to manage and invoke BPEL processing workflows.

Reference

Note: The trailing slash in URLs is optional.

Pipeline Overview

Returns a listing of all currently deployed BPEL pipelines including URLs to access their definition.

URL:
```
http://<hostname>:8080/smila/pipeline/
```
.
Allowed methods: GET, no further parameters or request body
Response Status Codes:
- 200 OK: Successful execution
- 500 INTERNAL SERVER ERROR: Any error

= Get Pipeline Definition

Returns a JSON object with the pipeline definition. The object consists of the name of the pipeline and the BPEL XML code as a single string value.

URL:

http://<hostname>:8080/smila/pipeline/<workflow-name>/

.

Allowed methods: GET, no further parameters or request body
Response Status Codes:
- 200 OK: Successful execution
- 500 INTERNAL SERVER ERROR: Any error

Invoke Pipeline

Process a record with a selected pipeline. Returns the result record as a JSON object.

URL:

http://<hostname>:8080/smila/pipeline/process/

.

Allowed methods:
- POST (recommended): specify record to process as JSON request body.
- GET: specify record tp process in query parameters
Response Status Codes:
- 200 OK: Successful execution
- 400 BAD REQUEST: Empty input record or invalid JSON.
- 405 METHOD NOT ALLOWED
- 500 INTERNAL SERVER ERROR: Other errors, e.g. error during processing.

Current Limitations

Exactly one non-empty input record must be sent, attachments cannot be added.
Only the first result record is returned, attachments are ignored.
The request is executed using a transient blackboard, so the records are not persisted to RecordStore.

Example Session

Some Tool recommendations

You can use tools like CURL or Resty to invoke HTTP APIs from the command line. More convenient are browser extensions like RESTClient or Posterfor Firefox, cREST for Chrome or Simple REST Client for Opera. And, of course, there are Plugins for Eclipse like restclient-tool.

For sake of simplicity, the following examples were produced with Resty.

In these examples we'll try to invoke the standard SearchPipeline using the JSON HTTP requests. First without any query:

> resty http://localhost:8080
http://localhost:8080*
> GET /smila/pipeline/SearchPipeline/process/
{
  "message" : "Cannot process an empty record."
}
> POST /smila/pipeline/SearchPipeline/process/
{
  "message" : "Cannot process an empty record."
}

So this did not work, as expected. In the response headers you can see the error code returned:

> POST /smila/pipeline/SearchPipeline/process/ -v
...
< HTTP/1.1 400 Bad Request
...
{
  "message" : "Cannot process an empty record."
}

So we add a query attribute:

> POST /smila/pipeline/SearchPipeline/process/ '{ "query": "SMILA" }'
...
< HTTP/1.1 500 Server Error
...
{
  "message" : "Error processing BPEL workflow SearchPipeline: Invocation of pipeline element SearchPipeline/search failed: Error processing message SearchPipeline-7afe423a-749c-4492-aa66-38ce37dba672\ncaused by: Invocation of pipeline element SearchPipeline/search failed: Error processing message SearchPipeline-7afe423a-749c-4492-aa66-38ce37dba672\ncaused by: no single value for required parameter QueryAttribute"
}

This time the LuceneSearchPipelet complains about a missing parameter. So let's add it:

> POST /smila/pipeline/SearchPipeline/process/ '{ 
    "query": "SMILA", 
    "QueryAttribute": "Content" }' 
{
  "query" : "SMILA",
  "QueryAttribute" : "Content",
  "_recordid" : "SearchPipeline-5c2d3f3f-1e56-4362-aa4c-74aa5fa9d6e8",
  "count" : 58,
  "indexSize" : 115,
  "records" : [ {
    "_recordid" : "feeds:<Uri=tag:search.twitter.com,2005:69739397733560320>",
    "_source" : "feeds",
    "_weight" : 0.84
  }, {
    "_recordid" : "feeds:<Uri=tag:search.twitter.com,2005:69960011966713856>",
    "_source" : "feeds",
    "_weight" : 0.73
  }, 
  ...
  ] }
}

A successful search ... but we probably want to see a bit more information. So we add values for parameter "resultAttributes":

> POST /smila/pipeline/SearchPipeline/process/ '{ 
  "query": "SMILA", 
  "QueryAttribute": "Content", 
  "resultAttributes": [ "Title", "Author", "LastModifiedDate" ] }' 
{
  "query" : "SMILA",
  "QueryAttribute" : "Content",
  "resultAttributes" : [ "Title", "Author", "LastModifiedDate" ],
  "_recordid" : "SearchPipeline-2201c83a-a9b6-4cfe-a62e-6ec8ffe113ca",
  "count" : 58,
  "indexSize" : 115,
  "records" : [ {
    "_recordid" : "feeds:<Uri=tag:search.twitter.com,2005:69739397733560320>",
    "_source" : "feeds",
    "_weight" : 0.84,
    "Title" : "@AbrarAlAdwani smila 3alech. Latwaswiseen",
    "Author" : "dee_the_bee (Dalalee Boland)",
    "LastModifiedDate" : "2011-05-15T14:22:22.000+0200"
  }, {
    "_recordid" : "feeds:<Uri=tag:search.twitter.com,2005:69960011966713856>",
    "_source" : "feeds",
    "_weight" : 0.73,
    "Title" : "Finally found something to smila bout :)",
    "Author" : "MIGUELALMENDRAL (Miguel FG Almendral)",
    "LastModifiedDate" : "2011-05-16T04:59:01.000+0200"
  },
  ...
  ] }
}

Awesome! In the same way you can add more parameters as you need:

> POST /smila/pipeline/SearchPipeline/process/ '{ 
    "query": "SMILA", 
    "QueryAttribute": "Content", 
    "resultAttributes": [ "Title", "Author", "LastModifiedDate" ], 
    "maxcount": 1, "offset": 42, "highlight": "Content" }' 
{
  "query" : "SMILA",
  "QueryAttribute" : "Content",
  "resultAttributes" : [ "Title", "Author", "LastModifiedDate" ],
  "maxcount" : 1,
  "offset" : 42,
  "highlight" : "Content",
  "_recordid" : "SearchPipeline-f2a53434-36b1-4e25-a716-f8c02fba5ecd",
  "count" : 58,
  "indexSize" : 115,
  "records" : [ {
    "_recordid" : "feeds:<Uri=http://www.eclipse.org/forums/index.php/mv/msg/206311/660699/#msg_660699>",
    "_source" : "feeds",
    "_weight" : 0.19,
    "Title" : "Re: New SMILA tryout",
    "Author" : "Andreas Weber",
    "_highlight" : {
      "Content" : {
        "text" : "<br />\n&#62;<br />\n&#62; I've done all standard steps as we do when creating a new<br />\n&#62; <b>SMILA</b>-workspace (and as described...-workspace (and as described on the <b>SMILA</b> website - dont know the<br... website - dont know the<br />\n&#62; exact name right now):<br />\n&#62;<br />\n&#62;<br />\n&#62; check out from eclipse SVN<br />\n&#62; add a new Target Platform with path to the <b>SMILA</b> bundles and to eclipse<br..."
      }
    }
  } ]
}

You can also use GET and URL parameters to invoke the pipeline, just enter something like this in the address line of your favorite browser:

http://localhost:8080/smila/pipeline/SearchPipeline/process?query=SMILA&QueryAttribute=Content

However, this gets inconvenient if you want to add lots of parameters and attributes.

@@ Line 7: / Line 7: @@
 === Reference ===
-* URL: <pre>http://<hostname>:8080/smila/pipeline/<workflow-name>/process/</pre>. The trailing slash is optional.
+Note: The trailing slash in URLs is optional.
-* Allowed methods: GET and POST
+==== Pipeline Overview ====
+Returns a listing of all currently deployed BPEL pipelines including URLs to access their definition.
+* URL: <pre>http://<hostname>:8080/smila/pipeline/</pre>.
+* Allowed methods: GET, no further parameters or request body
+* Response Status Codes:
+** 200 OK: Successful execution
+** 500 INTERNAL SERVER ERROR: Any error
+==== Get Pipeline Definition ===
+Returns a JSON object with the pipeline definition. The object consists of the name of the pipeline and the BPEL XML code as a single string value.
+* URL: <pre>http://<hostname>:8080/smila/pipeline/<workflow-name>/</pre>.
+* Allowed methods: GET, no further parameters or request body
+* Response Status Codes:
+** 200 OK: Successful execution
+** 500 INTERNAL SERVER ERROR: Any error
+==== Invoke Pipeline ====
+Process a record with a selected pipeline. Returns the result record as a JSON object.
+* URL: <pre>http://<hostname>:8080/smila/pipeline/process/</pre>.
+* Allowed methods:
+** POST (recommended): specify record to process as JSON request body.
+** GET: specify record tp process in query parameters
 * Response Status Codes:
+** 200 OK: Successful execution
 ** 400 BAD REQUEST: Empty input record or invalid JSON.
 ** 405 METHOD NOT ALLOWED
 ** 500 INTERNAL SERVER ERROR: Other errors, e.g. error during processing.
-==== Current Limitations ====
+===== Current Limitations =====
 * Exactly one non-empty input record must be sent, attachments cannot be added.
 * Only the first result record is returned, attachments are ignored.
+* The request is executed using a transient blackboard, so the records are not persisted to RecordStore.
 === Example Session ===

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Difference between revisions of "SMILA/Documentation/Processing/JSON REST API for BPEL pipelines"

Revision as of 03:29, 18 May 2011

Contents

Processing JSON REST API

Reference

Pipeline Overview

= Get Pipeline Definition

Invoke Pipeline

Current Limitations

Example Session

Breadcrumbs

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Difference between revisions of "SMILA/Documentation/Processing/JSON REST API for BPEL pipelines"

Revision as of 03:29, 18 May 2011

Contents

Processing JSON REST API

Reference

Pipeline Overview

= Get Pipeline Definition

Invoke Pipeline

Current Limitations

Example Session