REST API

Seldon Deploy API

Warning

Seldon Deploy’s REST API is considered experimental. The following endpoints could change at any time and breaking changes are expected.

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.

Note

These usage examples assume that you have already obtained an access token following the instructions of the Authentication section.

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"

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.

OIDC Client

In general, to authenticate against an OIDC provider, we will assume that the password flow is supported and that the OIDC client is public.

In Keycloak, this can be set by enabling Direct Access Grants and setting the client as open through the client dashboard in the admin UI.

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.

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