Wallaroo MLOps API Essentials Guide
Basic Guide for the Wallaroo API
The Wallaroo API provides users the ability to commands to a Wallaroo instance via a RCP-like HTTP API interface. This allows organizations to develop applications that can administrate Wallaroo from their own custom applications.
Each instance of Wallaroo provides the Wallaroo API specifications through the following URLs. Wallaroo uses the following format for its URLs. For more information, see the DNS Integration Guide.
https://{Wallaroo Prefix}{Service}{Wallaroo Suffix}
.
Page | URL | Description |
---|---|---|
Wallaroo Instance API URL | https://{Wallaroo Prefix}.api.{Wallaroo Suffix}/v1/api |
Address for the Wallaroo instance’s API. API requests will be submitted to this instance. |
Wallaroo Instance API Documentation | https://{Wallaroo Prefix}.api.{Wallaroo Suffix}/v1/api/docs |
A HTML rendered view of the Wallaroo API specification. |
Wallaroo Documentation Site | https://docs.wallaroo.ai/ | Wallaroo Documentation Site |
Wallaroo Enterprise Keycloak Service | https://{Wallaroo Prefix}.keycloak.{Wallaroo Suffix} |
Keycloak administration console for managing users and groups. It is recommended not to interfere with this service unless necessary. |
Wallaroo Enterprise Token Request URL | https://{Wallaroo Prefix}.keycloak.{Wallaroo Enterprise Suffix}/auth/realms/master/protocol/openid-connect/token |
The Keycloak token retrieval URL. |
For example, if the Wallaroo Enterprise Prefix is wallaroo
and the suffix is example.com
, the URLs would be as follows:
Page | Example URL |
---|---|
Wallaroo Instance API URL | https://wallaroo.api.example.com/v1/api |
Wallaroo Instance API Documentation | https://wallaroo.api.example.com/v1/api/docs |
Wallaroo Documentation Site | https://docs.wallaroo.ai/ |
Wallaroo Enterprise Keycloak Service | https://wallaroo.keycloak.example.com |
Wallaroo Token Request URL | https://{Wallaroo Prefix}.keycloak.example.com/auth/realms/master/protocol/openid-connect/token |
Each MLOps API operation requires a valid JSON Web Token (JWT) obtained from Wallaroo’s authentication and authorization service (i.e., Keycloak). Generally, the JWT must include a valid user’s identity, as Wallaroo access permissions are tied to specific platform users.
To authenticate to the Wallaroo API, the options are either to authenticate with the client secret, or to use the SDK command Wallaroo.auth.auth_header()
to retrieve the HTTP header including the token used to authenticate to the API.
The following process will retrieve a token using the client secret:
Wallaroo comes pre-installed with a confidential OpenID Connect client. The default client is api-client
, but other clients may be created and configured.
As it is a confidential client, api-client requires its secret to be supplied when requesting a token. Administrators may obtain their API client credentials from Keycloak from the Keycloak Service URL as listed above and the prefix /auth/admin/master/console/#/realms/master/clients
.
For example, if the Wallaroo instance DNS address is https://magical-rhino-5555.wallaroo.dev
, then the direct path to the Keycloak API client credentials would be:
https://magical-rhino-5555.keycloak.wallaroo.dev/auth/admin/master/console/#/realms/master/clients
Then select the client, in this case api-client, then Credentials.
By default, tokens issued for api-client are valid for up to 60 minutes. Refresh tokens are supported.
To retrieve an API token for a specific user with the Client Secret, request the token from the Wallaroo instance using the client secret and provide the following:
For example, the following requests a token for the Wallaroo instance https://magical-rhino-5555.wallaroo.dev
for user mary.jane@example.com
with the OpenID Connect Client api-client
:
TOKENURL = 'https://magical-rhino-5555.keycloak.wallaroo.dev/auth/realms/master/protocol/openid-connect/token'
CLIENT ='api-client'
SECRET = 'abc123'
USERNAME = 'mary.jane@example.com'
PASSWORD = 'snugglebunnies'
TOKEN=$(curl 'https://magical-rhino-5555.keycloak.wallaroo.dev/auth/realms/master/protocol/openid-connect/token' -u "$CLIENT:$SECRET" -d "grant_type=password&username=$USERNAME&password=$PASSWORD" -s | jq -r '.access_token')
With the token retrieve, a MLOps request can be performed.
The following example shows how to make the request using curl
to retrieve a list of workspaces:
curl 'https://magical-rhino-5555.api.wallaroo.ai/v1/api/workspaces/list' -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{}'
The same can be done through the Python requests
library:
## Inference through external URL
apiRequest = "https://magical-rhino-5555.api.wallaroo.ai/v1/api/workspaces/list"
# set the headers
headers= {
'Authorization': 'Bearer ' + TOKEN,
'Content-Type: application/json'
}
data = {
}
# submit the request via POST
response = requests.post(apiRequest, data=data, headers=headers)
# Display the returned result
print(response.json())
Basic Guide for the Wallaroo API