Stambia offers the possibility to expose Web Services on the Runtime.
Every Mapping or Process can be easily published as a Web Service with a simple click.
Then, third party applications can invoke them through the Runtime's endpoints (HTTP REST and SOAP).
This article summarizes how to publish/expose Web Services, with some tips and useful information.
You can follow the Invoking Web Services and Publishing Web Services Tutorials integrated in the Designer's Help Contents for more detailed and step by step examples.
Publishing a Delivery as a Web Service
Any Process or Mapping can be published as a Web Service.
- Processes allows to customize the Input and Output of the Web Service
- Mappings can be directly exposed as a Web Service when the execution does not need Input / Output
Preparation / Advises
Deliveries which are exposed as a Web service, will probably run in parallel (when several web service invocations occur at the same time).
Take care of this parallelism when developing (unique file names, temporary tables...).
Important:
Deliveries using JSON inputs/outputs can only be accessed through the HTTP Rest Endpoint #2 (or higher), available since Runtime S17.3.0
Development
The first step is to create the Process or Mapping that will represent your web service.
Simply design them as usual, they are not different as other Stambia developments.
If you need to set Input or Output parameters for your Web Service see below, otherwise, when your have finished your development, see 'Publishing the Web Service'.
Input and output parameters
Your web service can be configured to have input and output parameters, which must be defined on the main process.
The following parameters can be used as input/output:
standard
- Process Parameters
- Tables
- XML nodes
- JSON nodes
- File metadata
advanced
- URL Parameters (only as input)
- HTTP Headers
- HTTP Response Code (only as output)
Standard Parameters
Simply drag and drop the desired object on your Process and configure the Publication:
- Check "Input" if you want it to be an input parameter.
- Check "Output" if you want it to be an output parameter.
Advanced Parameters
URL Parameters
Url Parameters are retrieved directly from the path of the request.
E.g. http://stambia:42200/rest/StambiaDeliveryService/2/myDelivery/id/2
In this example, 'id' and '2' are Url Parameters.
Refer to this article for more details.
HTTP Headers
The HTTP headers sent with the request to the Web Service can be retrieved and mapped automatically to Process Parameters.
This allows to use them in your Web Service.
Moreover, you can also define as many output HTTP headers as you want, that will be returned at the end of the Web Service invocation.
Refer to this article for more details.
HTTP Response Code
The HTTP Response Code returned at the end of the Web Service invocation can be customized.
This allow to return the exact code you need, depending on the rules of your Process.
Refer to this article for more details.
HTTP Response Body / Message
The HTTP Response Body returned at the end of the Web Service invocation can be customized.
This allow to return the exact message you need, depending on the rules of your Process.
Refer to this article for more details.
Publishing the web service
When you are ready to deploy your Process / Mapping as a Web Service, simply right click on it, and choose 'Publish -> As WebService'.
This will deploy it automatically to the connected Runtime, that will expose it.
Your Web Service is then immediately available at invocation.
Warning:
Do not forget to re-publish your Process / Mapping each time you made a modification on it.
Tip:
You can also publish a Delivery as a Web Service from Analytics.
For this, import the Process package in your Analytics Deployment Manager and check the 'Expose As WebService' checkbox on the Deployment Specification.
Invoking the Web Service
You can now invoke the Web Service with HTTP REST or SOAP. E.g.
Available Endpoints
All the available HTTP REST and SOAP endpoints' URLs for a given runtime can be found on the console at startup or in the "com.indy.engine.<rmiPort>.log" log file.
SOAP Endpoints
SOAP Endpoint is by default:
HTTP REST Endpoints
HTTP REST endpoint is by default:
By default, all verbs are accepted (GET, POST, PUT, DELETE, ...)
Standard response code
| HTTP Response code | Case |
| 200 : OK | when the process has been successully executed |
| 500 : Internal Server Error | when the process has finished in error, the error message is sent the body |
If your want to costumize the response code, please refer to this article for more details.