You are viewing the RapidMiner Server documentation for version 9.3 - Check here for latest version

Create a web service

What is a web service?

See also the video introduction to web services.

In the context of RapidMiner, a web service is a process that can be called by means of a URL. The URL is a link to RapidMiner Server, similar to the following:

http://RMServerHost:8080/api/rest/process/YourServiceName?customerID=3

The URL can take a query parameter as input, in this example customerID=3, and it delivers a result in a format of your choice, including the following:

JSON
XML
HTML
OData
and others...

To see the results, either you must authenticate yourself as a registered user, or RapidMiner Server must be configured to accept queries by anonymous users. The URL for a web service available to anonymous users will take the following slightly different form:

http://RMServerHost:8080/api/rest/public/process/YourServiceName?customerID=3

Notice the reference to public in the URL.

However, in a typical web-service scenario, you won't call this URL yourself. You will build an app to serve some useful purpose, and the app will call the URL, authenticating itself via a token. Web services can easily be embedded into web pages and other applications. They make it possible to serve the results of a RapidMiner process over HTTP.

Before you begin

Before creating a web service, make sure that:

RapidMiner Server is installed and configured.
RapidMiner Studio is connected to the remote repository.
The process you want to implement as a web service is saved in the server repository.
Your process is designed so that the data you need is delivered to the first result ("res") port. A web service returns data only from the first port.

If you don't yet have a process to implement as a web service, or you are unsure how to build such a process, you may find it helpful to work through an example. In Predictive Maintenance, we explicitly build two processes that, in the remainder of this document, are implemented as web services.

Step by step

See also the video introduction to creating a web service, including a discussion of the anonymous user and of some security precautions you need to take when providing public access to RapidMiner Server.

At the conclusion of Predictive Maintenance, we saved two new processes to a RapidMiner Server repository:

Predictive_Maintenance_web_service_without_parameters, to predict the probability of failure for all values of "Machine ID". This process has no macro, and the URL will not include a query parameter.
Predictive_Maintenance_web_service_with_parameters, to predict the probability of failure for a particular value of "Machine ID". This process contains a macro, and when the web service is created, the URL will include a query parameter corresponding to a particular value of "Machine ID".

Let us create web services for both of them, taking the following steps:

Create a web service. Select one of the following entry points:
- In RapidMiner Studio, in the server repository, right-click on the process and choose Browse to open the Repository Browser on RapidMiner Server. Click Export as Web Service.
- On RapidMiner Server, choose Repository > Browse Repository, navigate to the process of interest, select it, and click Export as Web Service.
- On RapidMiner Server, choose Processes > Web Services, and click on Create new web service.
Of these, the first is perhaps the best, because it takes you directly to the process of interest.

The screenshot below shows the Edit Web Service dialog for the second process, Predictive_Maintenance_web_service_with_parameters. Notice that RapidMiner Server automatically detects the macro in this process, and assigns a URL query parameter with the same name. You can if you like change the query parameter. You can also change the Service ID; it need not be the same as the process name. However, the Data source must accurately locate the process on RapidMiner Server, and the macro name must be the same as the one that was written in that process. If you look at the drop-list for the Output format, you will see that there are numerous options. In this example, we have chosen "JSON"; RapidMiner Server sets the MIME-type accordingly.
Edit web service. Make sure to fill in the following fields:
- Service ID: the name of the web service, as it will appear in the URL. It need not be the same as the process name.
- Data source: the location of the process on RapidMiner Server
- Output format: the output format. Choices include JSON, XML, HTML, OData, and others.
- Parameter binding: The URL query parameter, if it exists, need not be the same as the macro name.
Click Submit to save the process as a web service.

The page that opens next (Processes > Web Services) lists available web services by their ID. Here you have the opportunity to test the the web service and to edit the web service, if necessary. You can also delete it.

With parameters

When you test the service Predictive_Maintenance_web_service_with_parameters, with JSON output, the result is the following. To test the functioning of the URL query parameter, you can change the value and click Test.

Once the web service is ready, you can call it from the browser via the Direct Link listed on the right side of the page, or you can embed the result in an <iframe> by following the instructions under Embeddable HTML Code.

With RapidMiner Server running locally on a laptop, the URL takes the following form:

http://localhost:8080/api/rest/process/Predictive_Maintenance_web_service_with_parameters?machineID=M_0221

In general, localhost will be replaced by your RapidMiner Server hostname. Suppose that when creating the web service we had given a simpler name, such as "needs-repair", to the web service ID. Then the URL would have been simpler:

http://localhost:8080/api/rest/process/needs-repair?machineID=M_0221

but in either case, with JSON output, the result is the same:

{
   "Machine_ID":"M_0221",
   "confidence(no)":0.10256410256410256,
   "confidence(yes)":0.8974358974358979,
   "prediction(Failure)":"yes"
}

Without parameters

When you test the service Predictive_Maintenance_web_service_without_parameters, with Table output, the result is the following:

Again, once the web service is ready, you can call it from the browser via the Direct Link listed on the right side of the page, or you can embed the result in an <iframe> by following the instructions under Embeddable HTML Code.