Categories

Versions

  1. Documentation
  3. Hub
  4. Endpoints
  5. Request results

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:

  1. Identify the endpoint URL
  2. Identify the endpoint security method
  3. Format the input data as JSON
  4. 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 or example.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 Altair AI Hub, by clicking on the icons under Endpoint Actions.

../create/img/endpoint-deployed.png

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 Altair 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.

img/endpoint-test.png

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)
Privacy Policy © 2024 Altair Engineering Inc. All Rights Reserved. We are currently listed on Nasdaq as ALTR.