Web API endpoints
This document takes the place of the Real-Time Scoring documentation in RapidMiner 10.1 and previous.
For a quick review, see the summary Real-Time Scoring page
Wouldn't it be great if the results of your 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.
A scoring agent executes processes via a REST API.
An endpoint is a 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 Altair AI Hub. Notice that a regular scoring agent has no connection to Altair 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 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 Altair 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 Altair 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 Altair 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 Altair AI Hub is already installed, with the scoring-agent profile, you can probably skip this step. A Web API agent is built in to Altair AI Hub.
However, if for some reason you want to install the endpoint infrastructure independently of Altair AI Hub, here are your options:
- standalone, without Docker or Kubernetes, or using
- Docker or
- Kubernetes.
(user) Create a process
(user) Create an endpoint
When your process is ready to go, create an endpoint. The details depend on the details of your endpoint infrastructure:
- If you are using Altair AI Hub's built-in Web API agent, use the wizard to create an endpoint.
- If you have installed the endpoint infrastructure independently of Altair 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 data table format (
.rmhdf5table), - submits the data table as input,
- runs the endpoint process, and
- converts the output back to JSON, returning it to you.
- converts the JSON to data table format (