Version: 1.3.0

Gravitino REST API

The Gravitino REST API manages everything in Datastrato Enterprise: metalakes, catalogs and the objects in them, tags and policies, users, groups, roles and privileges, lineage, and jobs. The Enterprise UI, the Java and Python clients, and the engine connectors all work through it.

Base URL and headers

Every path in this reference is relative to https://{gravitino_host}/api, the address of the Gravitino server with /api added. Send Accept: application/vnd.gravitino.v1+json on every call, and Content-Type: application/json on calls that send a body.

The Accept value is required: a call that asks for application/json instead is refused with HTTP 406. Responses come back labeled Content-Type: application/json. Each page of this reference lists the Gravitino media type under its responses because that is the value the request must send.

List the metalakes

curl -sS -u "admin:$ADMIN_PASSWORD" \
  -H "Accept: application/vnd.gravitino.v1+json" \
  "https://{gravitino_host}/api/metalakes"

Responses

A successful call returns HTTP 200 with "code": 0 and the result. A failed call returns an HTTP error status and a body that names the problem:

Example error response

{
  "code": 1003,
  "type": "NoSuchCatalogException",
  "message": "Failed to operate catalog(s) [sales] operation [LOAD] under metalake [acme], reason [Catalog acme.sales does not exist]"
}

Testing a catalog connection is the exception: a failed test returns HTTP 200 with a nonzero code and the reason in message.

Every call is checked against the caller's roles, and a call the roles do not allow returns HTTP 403; see Privileges.

Authentication

Every call except the health checks needs credentials. The server accepts two kinds, depending on how it is configured:

• A user name and password, for the admin user and local users, sent as HTTP basic credentials.
• A bearer token issued by the identity provider Gravitino is configured for, for users who sign in through it.

Call the API as a local user

curl -sS -u "{user}:{password}" \
  -H "Accept: application/vnd.gravitino.v1+json" \
  "https://{gravitino_host}/api/metalakes"

Call the API with a bearer token

curl -sS -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/vnd.gravitino.v1+json" \
  "https://{gravitino_host}/api/metalakes"

The code samples on each page show the bearer form. A local user replaces the Authorization line with -u "{user}:{password}". Setting the server up for each kind is covered in Authentication. Kerberos is not configurable through the Helm chart in this release.

Other APIs

API	Use it to	See
Iceberg REST catalog	Read and write Iceberg tables from Spark, Trino, Flink, PyIceberg and other engines, using the standard Apache Iceberg REST protocol on its own port	Iceberg REST catalog service
Lance REST	Work with Lance tables using the Lance REST namespace protocol	Lance REST service
SCIM 2.0	Provision users and groups from an identity provider	SCIM provisioning
Metrics	Scrape server metrics in Prometheus format	Metrics
Java and Python clients	Call this API from code without building requests by hand	Java client, Python client

The Enterprise UI lists the address of each of these endpoints on a running server; see Client access.

Authentication

OAuth 2.0: OAuth2WithJWT

A bearer token issued by the identity provider Gravitino is configured for. The token URL shown is a placeholder; use your identity provider's token endpoint. See Authentication.

Security Scheme Type:	oauth2
OAuth Flow (clientCredentials):	Token URL: https://external-oauth-server.com/token Scopes: serviceAudience: The audience name when Gravitino uses OAuth as the authenticator.

HTTP: Basic Auth

A user name and password, for the admin user and local users. See Authentication.

Security Scheme Type:	http
HTTP Authorization Scheme:	basic

Kerberos Auth

Kerberos is not configurable through the Helm chart in this release.

Security Scheme Type:	http
HTTP Authorization Scheme:	negotiate

License

Apache 2.0