REST API

Seldon Deploy’s REST API

The REST API of Seldon Deploy lets you to interact with your machine learning deployments programmatically. This allows you to build complex deployment pipelines to integrate Seldon Deploy with any upstream services.

overview

If you already have access to a Seldon Deploy installation, you can visit the interactive API reference to learn more about the Seldon Deploy API and the endpoints that it exposes. The interactive API documentation can be accessed by clicking on your profile icon, and then clicking on API Docs. Alternatively, you can go directly to $ML_PLATFORM_HOST/seldon-deploy/swagger/, where $ML_PLATFORM_HOST needs to be replaced by the domain where your Seldon Deploy installation can be accessed.

Usage

The recommended way of interacting with the Seldon Deploy REST API is through its Python SDK. However, you can also use plain cURL to send requests.

You can find some example usages below.

We can use cURL (available on most distributions) or similar HTTP clients to interact directly with the Seldon Deploy API.

For example, if we assume that there is an authentication token present in the $TOKEN variable, we could list our machine learning deployments as:

ML_PLATFORM_HOST="https://ml.example.com"
curl -k -X GET \
  "$ML_PLATFORM_HOST/seldon-deploy/api/v1alpha1/namespaces/staging/seldondeployments" \
  -H "Authorization: Bearer $TOKEN"

To use the Python SDK, the first step will be to install the seldon-deploy-sdk package. You can do so using pip as:

pip install seldon-deploy-sdk

Once we have obtained an authentication token, we will need to set it as the access_token of our Configuration object. Afterwards, we could list all our machine learning deployments under the staging namespace as:

from seldon_deploy_sdk import Configuration, ApiClient, SeldonDeploymentsApi

config = Configuration()
config.host = "http://ml.example.com/seldon-deploy/api/v1alpha1"
config.access_token = "<AUTH_TOKEN>"

api_client = ApiClient(config)

# List current machine learning deployments
sdep_api = SeldonDeploymentsApi(api_client)
sdeps = sdep_api.list_seldon_deployments("staging")

print(sdeps)

You can find more details on the Python SDK reference documentation.

Authentication

All requests to the Seldon Deploy API must be authenticated. Therefore, before using the API you must obtain an authentication token. Note that the process to issue a new authentication token may change depending on your architecture and your OIDC provider.

You can see some authentication examples below.

We can use plain cURL to obtain a token, by emulating OpenID’s password flow.

If we assume a set up where Keycloak is configured as an OIDC provider and that there is an OpenID client named sd-api, we could obtain an authorization token to access the API using plain cURL as:

SD_USER="data-scientist-1@example.com"
SD_PASSWORD="12341234"
CLIENT_ID="sd-api"

KEYCLOAK_HOST="https://auth.example.com"
KEYCLOAK_REALM="deploy-realm"

_payload="username=$SD_USER&password=$SD_PASSWORD&grant_type=password&client_id=$CLIENT_ID&scope=openid"
_authEndpoint="$KEYCLOAK_HOST/auth/realms/$KEYCLOAK_REALM/protocol/openid-connect/token"
RESULT=$(curl -k -s --data $_payload $_authEndpoint)
TOKEN=$(echo $RESULT | sed 's/.*id_token":"//g' | sed 's/".*//g')

echo "TOKEN=$TOKEN"

Note that this example also assumes that the sd-api OpenID client is public and that it supports the password flow.

Out of the box, the Python SDK supports a set of common authentication workflows. Each of these, can be found under the seldon_deploy_sdk.auth package.

  • SessionAuthenticator: Allows you to authenticate against Dex, configured as an ingress-level authentication provider. This is equivalent to Seldon Deploy’s default Kubeflow setup.
  • OIDCAuthenticator: Allows you to authenticate against an OIDC-compatible provider, using the password flow. This is equivalent to Seldon Deploy’s default trial setup.

As an example, let’s assume a set up where Keycloak is configured as an OIDC provider and there is an OpenID client named sd-api, under a realm named deploy-realm. Note that this architecture is equivalent to Seldon Deploy’s default trial installation. Under these conditions, we could obtain an access token, using the seldon_deploy_sdk.auth.OIDCAuthenticator helper, as:

from seldon_deploy_sdk import Configuration
from seldon_deploy_sdk.auth import OIDCAuthenticator

sd_user = "data-scientist-1@example.com"
sd_password = "12341234"

config = Configuration()
config.host = "http://ml.example.com/seldon-deploy/api/v1alpha1"
config.oidc_client_id = "sd-api"
config.oidc_server = "http://ml.example.com/auth/realms/deploy-realm"
# For private OpenID clients:
# config.oidc_client_secret = "my-secret"

# Authenticate against an OIDC provider
auth = OIDCAuthenticator(config)
access_token = auth.authenticate(sd_user, sd_password)

# Configure the obtained access token as the one to use downstream
config.access_token = access_token
print(config.access_token)

You can find more details on the Python SDK reference documentation.

Versioning

The API endpoints are versioned to avoid clashes between different versions of the API. The current version of the API is v1alpha1, which means that breaking changes are still highly likely to happen. Once the current version graduates to stable, it will be renamed to v1.

Note that this versioning schema is similar to the one followed in Kubernetes.

Reference


API Reference (v1alpha1)

Reference for version v1alpha1 of the API.

Last modified March 25, 2021