You are viewing the RapidMiner Hub documentation for version 10.3 - Check here for latest version
Request results
Previous: Create an endpoint
Having created an endpoint process and an endpoint, we are now in a position to request results via the endpoint URL. There are four steps:
- Identify the endpoint URL
- Identify the endpoint security method
- Format the input data as JSON
- POST the data to the endpoint URL
Note that you are free to use any software that supports HTTP POST to communicate with the endpoint URL -- that's a large set of programs!
In addition, all in-depth snippets to call the endpoint can also be previewed in the "Test" page for an endpoint.
Identify the endpoint URL
In general, a Web API endpoint URL will take the following form:
http://$SA_HOST/$WEB_API_GROUP/api/v1/services/$deployment_path/$alias
where
$SA_HOST
is the host name of the scoring agent (e.g.,example.com/webapi
orexample.com:8099
)$WEB_API_GROUP
is the name of the Web API group to which the endpoint belongs$deployment_path
is the name you chose when you created the endpoint$alias
is the alias you assigned to the endpoint process, possibly the process name
In our example based on the Iris data set, the endpoint URL resolves as follows:
http://example.com/webapi/DEFAULT/api/v1/services/iris/identify
You can discover the endpoint URL for your endpoint within the Endpoints menu of RapidMiner AI Hub, by clicking on the icons under Endpoint Actions.
Identify endpoint's security
A Web API Deployment (all of it's exposed Endpoint URLs) can be secured via
- Anonymous (not secured and publicly accessible),
- Basic,
- AI Hub and
- Long-living API Token
authentication methods.
Endpoints support multiple security methods at the same time. During creation, this can be set up.
When calling an endpoint URL, the required request headers differs depending on the enabled security methods.
Endpoint security: anonymous
If an Endpoint is not secured, no special header attribute needs to be given when invoking the request.
Example:
curl http://example.com/webapi/DEFAULT/api/v1/services/iris/identify \
-X POST \
-H "Content-type: application/json" \
-d "{\"data\":[{\"a1\":5.1,\"a2\":3.5,\"a3\":1.4,\"a4\":0.2}]}"
Endpoint security: basic
If a Web API Deployment and all of its Endpoints have been set up with basic auth, one of the statically configured
credentials (during creation) need to be provided to the request. Remember, that credentials
need to be properly encoded to Basic format (see the -u
parameter of curl
in the example call below which
automatically does the encoding).
Example:
curl http://example.com/webapi/DEFAULT/api/v1/services/iris/identify \
-X POST \
-u "user:password" \
-H "Content-type: application/json" \
-d "{\"data\":[{\"a1\":5.1,\"a2\":3.5,\"a3\":1.4,\"a4\":0.2}]}"
Endpoint security: AI Hub (OAuth2 via platform's Keycloak)
If an Endpoint is secured via AI Hub permissions, then any valid AI Hub user or group can be granted access during creation. This means, that accessing the Endpoint itself requires a valid access token (JSON Web Token) of a user who has access to AI Hub and is a registered account in AI Hub's Identity Provider application Keycloak.
To retrieve a valid accessToken
, please refer to the REST API documentation section
about Create a JWT using Keycloak.
After such a token has been generated, you can use it when calling an Endpoint by providing the necessary HTTP header with
-H "Authorization: Bearer <accessToken>"
in the curl
call.
Example:
curl http://example.com/webapi/DEFAULT/api/v1/services/iris/identify \
-X POST \
-H "Authorization: Bearer <accessToken>" \
-H "Content-type: application/json" \
-d "{\"data\":[{\"a1\":5.1,\"a2\":3.5,\"a3\":1.4,\"a4\":0.2}]}"
Endpoint security: Long-living API Token
Endpoints also support long-living API tokens. Those tokens have the special form of randomly generated sequence of
characters and numbers, e.g., 6f39c79c-1e4b-4d9e-b393-2fbb6ce35be8
. In addition, multiple of such long-living API tokens
can be attached to one Web API deployment during creation enabling different consumers to
use different tokens. Furthermore, each token can have its own expiration date and time.
During a request, such tokens are provided by adding the HTTP header with -H "Authorization: apitoken <token>"
in
the curl
call.
Example:
curl http://example.com/webapi/DEFAULT/api/v1/services/iris/identify \
-X POST \
-H "Authorization: apitoken <token>" \
-H "Content-type: application/json" \
-d "{\"data\":[{\"a1\":5.1,\"a2\":3.5,\"a3\":1.4,\"a4\":0.2}]}"
Format the input data as JSON
Your input data must be formatted as JSON, with two available data types: numeric and text, distinguished by the quotes (") around text values.
The scoring agent will transform the JSON format into rows and columns readable
by the endpoint process (rmhdf5table
) and provided to the first input port.
For example, a single row of input data for the process we created in connection with the Iris data set might take the following form.
{
"data": [
{
"a1": 5.1,
"a2": 3.5,
"a3": 1.4,
"a4": 0.2
}
]
}
Note that in JSON files, trailing commas are not permitted.
You can submit one row of data or multiple rows. In general, each row of input will consist of a single JSON object (in curly brackets), and the set of all rows is contained within a single JSON array (square brackets), as follows:
{ "data": [ {object1}, {object2}, {object3} ] }
POST the data to the endpoint URL
There are many ways of posting data to your endpoint URL. Try the following examples, after substituting your own input data and your own endpoint URL.
No matter what your method, the results are returned in JSON format, including both the input data and (in this example) the predictions.
{
"data": [
{
"a1": 5.1,
"a2": 3.5,
"a3": 1.4,
"a4": 0.2,
"confidence(Iris-setosa)": 1.0,
"confidence(Iris-versicolor)": 0.0,
"confidence(Iris-virginica)": 0.0,
"prediction(label)": "Iris-setosa"
}
]
}
Post data using the test page
Within the Endpoints menu of RapidMiner AI Hub, under Endpoint Actions, click on Test to get a test page for your endpoint. Insert your JSON-formatted input data and click Run Test.
Post data using curl
Note that the test page also includes the option Show curl command, pre-configured for your endpoint and your test data, in this example:
curl http://example.com/webapi/DEFAULT/api/v1/services/iris/identify \
-X POST \
-H "Content-type: application/json" \
-d "{\"data\":[{\"a1\":5.1,\"a2\":3.5,\"a3\":1.4,\"a4\":0.2}]}"
Alternatively, put your input data into a file (e.g, iris.json), and you can post it as follows -- here the generic form of the endpoint URL is given.
curl http://$SA_HOST/$WEB_API_GROUP/api/v1/services/$deployment_path/$alias \
--request POST \
--header "Content-Type: application/json" \
--data @iris.json
Post data using python
Use the requests library.
import requests
endpoint_url = 'http://example.com/webapi/DEFAULT/api/v1/services/iris/identify'
my_input_data = {"data":[{"a1":5.1,"a2":3.5,"a3":1.4,"a4":0.2}]}
r = requests.post(endpoint_url, json=my_input_data)
json_output = r.json()
print(json_output)