Web API endpoints
This document takes the place of the Real-Time Scoring documentation in RapidMiner 10.1 and previous.
Wouldn't it be great if the results of your RapidMiner processes were available from anywhere with a network connection, on any device -- preferably via an API, so that the results could be utilized by other programs?
It's possible! Since a picture is worth a thousand words, consider the following schematic that describes the essential functionality of the scoring agent.
A scoring agent executes RapidMiner processes via a REST API.
An endpoint is a RapidMiner process, made available by a scoring agent, that can be executed via a REST API.
A Web API agent is a type of scoring agent, but more specifically it is a smart scoring agent that communicates with RapidMiner AI Hub. Notice that a regular scoring agent has no connection to RapidMiner AI Hub.
The Web API agent knows about permissions and the status of projects, and it can adjust its behavior accordingly. In particular, it can automatically update its endpoint processes when a project is updated, streamlining and enhancing your developer workflow.
It follows from the previous discussion that a Web API endpoint is a RapidMiner process, made available by a Web API agent, that can be executed via a REST API.
If the Web API agent is so smart, why would I use a regular scoring agent?
Keyword: edge computing
Because with a regular scoring agent, you can have your endpoint anywhere you like: on your laptop, on a remote server, or on your Raspberry Pi! You don't even need a network connection, so long as your REST API calls are purely local. In short, you no longer depend on RapidMiner AI Hub.
The Web API agent that executes your processes is designed to be lightweight and fast! So if your process is slower – you’re building a model or executing some other long-running process – you should instead be reading about the job execution infrastructure.
See more architecture diagrams:
-
Because a Web API agent communicates with RapidMiner AI Hub, the Web API architecture has a somewhat more complex architecture, including Web API gateway and Web API registry.
-
This document describes the inner logic of the RapidMiner AI Hub architecture, concentrating on the essentials and ignoring peripheral components.
Step by step
The steps to arrive at this blissful state of affairs are the following:
(admin) Install the endpoint infrastructure
If RapidMiner AI Hub is already installed, with the scoring-agent profile, you can probably skip this step. A Web API agent is built in to RapidMiner AI Hub.
However, if for some reason you want to install the endpoint infrastructure independently of RapidMiner AI Hub, here are your options:
- standalone, without Docker or Kubernetes, or using
- Docker or
- Kubernetes.
(user) Create a process
Endpoints are connected to processes in your RapidMiner projects.
(user) Create an endpoint
When your RapidMiner process is ready to go, create an endpoint. The details depend on the details of your endpoint infrastructure:
- If you are using RapidMiner AI Hub's built-in Web API agent, use the wizard to create an endpoint.
- If you have installed the endpoint infrastructure independently of RapidMiner AI Hub, use the wizard to create a deployment ZIP, and then place that ZIP file in the deployments folder belonging to the endpoint infrastructure.
(user) Request results
To trigger a result, you have to POST some data in JSON format to the endpoint URL. The scoring agent
- converts the JSON to RapidMiner data table format,
- submits the data table as input,
- runs the endpoint process, and
- converts the output back to JSON, returning it to you.
