Overview #

Apache® Gravitino Server OpenAPI is a managed metadata service based on Apache® Gravitino. By providing standardized REST APIs, it enables users to centrally manage and discover data and AI assets scattered across different systems. This document is intended to provide external customers with instructions for using the core OpenAPI of Gravitino Server, helping customers quickly integrate this service into their existing data applications and workflows.

Apache Gravitino, the names of other Apache projects, and the ASF logo are either registered trademarks or trademarks of the Apache Software Foundation in the United States and/or other countries.

Concepts and mappings #

To ensure compatibility and consistency with the Volcengine ecosystem, it is necessary to understand the mapping relationships of the following core concepts before using Gravitino Server OpenAPI:

• Metalake: Corresponds to your Volcengine Account ID (Volcengine AccountId). Metalake is the highest-level unit for metadata isolation, serving as the boundary for all resources, permissions, and governance policies.
• Catalog: Maps to the Hive Catalog in the metadata service of LAS (Lakehouse Analytics Service). Catalog is a container for organizing and managing metadata, such as databases and tables.
• Schema: Refers to a database or schema, which is a collection of tables.
• Table: Definition of structured data, including columns, partitions, attributes, and other information.
• Fileset: Metadata abstraction for unstructured data, usually referring to a group of files.
• Topic: A topic in a message queue (such as Kafka).
• Model: Model metadata in AI/ML scenarios.

Preparation before use #

The following preparations must be completed before calling the API:

Obtain service access information #

• Service Endpoint: https://{endpoint} (please replace with the actual service address provided by Volcengine).
• Volcengine access key (AK/SK): Used for API request signing. Please securely obtain and manage your Access Key ID (AK) and Secret Access Key (SK) from the Volcengine console.

API request signature #

All requests to Gravitino Server OpenAPI must be signed to verify the identity of the requester and ensure data integrity during transmission. The signature mechanism follows Volcengine's unified standard.

• Signature algorithm: HMAC-SHA256
• Core request headers:
  • X-Date: UTC time, formatted as YYYYMMDDTHHMMSSZ, for example 20251117T083000Z.
  • Authorization: A string containing AK, signature version, timestamp, region, service, list of signature headers, and the final signature digest.

For detailed steps of signature calculation, pseudocode examples, and usage methods for SDKs in various languages, please refer to the official Volcengine documentation: Signature mechanism description
Signature step overview:

1. Construct canonical request (Canonical Request): Concatenate the HTTP method, URI, query string, request headers, and the hash value of the request body.
2. Create string to sign (String to Sign): Combine the signature algorithm, timestamp, credential scope, and the hash value of the canonical request.
3. Calculate signing key (Signing Key): Derive the signing key using SK and information such as time, region, and service.
4. Calculate final signature (Signature): Use the signing key to perform HMAC-SHA256 hashing on the string to sign.
5. Assemble Authorization header: Combine AK and the calculated signature information to form the final Authorization request header.

The following is a pseudocode example for generating a signature to help you understand the signing process:

# 1. Prepare input
AK = "{ak}" # Your Access Key ID
SK = "{sk}" # Your Secret Access Key
Region = "{region}" # For example: cn-beijing
Service = "las" # The service name is fixed as las
Host = "{endpoint}" # Service endpoint
Method = "POST"
Path = "/iceberg/v1/namespaces/{namespace}/tables"
Timestamp = "20251117T100000Z" # UTC time in ISO8601 format
Headers = "host;x-date"
RequestPayload = "{...}" # JSON content of the request body

# 2. Construct canonical request (Canonical Request)
CanonicalRequest = Method + '\n' + Path + '\n' + '' + '\n' + 'host:' + Host + '\n' + 'x-date:' + Timestamp + '\n' + '\n' + Headers + '\n' + Hex(SHA256(RequestPayload))

# 3. Construct string to sign (String to Sign)
StringToSign = "HMAC-SHA256" + '\n' + Timestamp + '\n' + Date(Timestamp) + '/' + Region + '/' + Service + '/request' + '\n' + Hex(SHA256(CanonicalRequest))

# 4. Calculate signing key (Signing Key)
DateKey = HMAC-SHA256(Date(Timestamp), "VOLC" + SK)
DateRegionKey = HMAC-SHA256(Region, DateKey)
DateRegionServiceKey = HMAC-SHA256(Service, DateRegionKey)
SigningKey = HMAC-SHA256("request", DateRegionServiceKey)

# 5. Calculate final signature (Signature)
Signature = Hex(HMAC-SHA256(StringToSign, SigningKey))

# 6. Construct Authorization Header
AuthorizationHeader = "HMAC-SHA256 Credential=" + AK + "/" + Date(Timestamp) + "/" + Region + "/" + Service + "/request, SignedHeaders=" + Headers + ", Signature=" + Signature

Core API description #

The following is the core OpenAPI interface description for Gravitino Server. All interfaces must be accessed via HTTP and follow the signature authentication method described in the "Preparation before use" section.

Query Metalake information #

Load detailed information for the specified Metalake. In the Volcano Engine environment, this usually corresponds to the current Volcano Engine account.

• Method: GET
• Path: /api/metalakes/{metalake_name}

Path parameters:

Request example:

curl -X GET 'https://{endpoint}/api/metalakes/your_account_id' \ 
--header 'X-Date: 20251117T090000Z' \
--header 'Authorization: HMAC-SHA256 Credential={ak}/20251117/{region}/gravitino/request, SignedHeaders=host;x-date, Signature={signature}'

Response example:

{
  "code": 0,
  "metalake": { 
    "name": "your_account_id",
    "comment": "This is a metalake for the current account.",
    "properties": {},
    "audit": {
      "creator": "system",
      "createTime": "2025-11-17T08:00:00Z"
    }
  }
}

Status codes and common errors:

• 200 OK: Request succeeded.
• 404 Not Found: The specified Metalake does not exist.

List Catalog #

List all Catalogs under the specified Metalake.

• Method: GET
• Path: /api/metalakes/{metalake_name}/catalogs

Request example:

curl -X GET 'https://{endpoint}/api/metalakes/your_account_id/catalogs' \
--header 'X-Date: 20251117T090500Z' \ 
--header 'Authorization: HMAC-SHA256 Credential={ak}/20251117/{region}/gravitino/request, SignedHeaders=host;x-date, Signature={signature}'

Response example:

{
  "code": 0,
  "identifiers": [
    {
      "namespace": [
        "your_account_id"
      ],
      "name": "hive_prod"
    }
  ]
}

Load Catalog #

Load detailed information for the specified Catalog.

• Method: GET
• Path: /api/metalakes/{metalake_name}/catalogs/{catalog_name}

Request example:

curl -X GET 'https://{endpoint}/api/metalakes/your_account_id/catalogs/hive_prod' \
--header 'X-Date: 20251117T091000Z' \
--header 'Authorization: HMAC-SHA256 Credential={ak}/20251117/{region}/gravitino/request, SignedHeaders=host;x-date, Signature={signature}'

Response example:

{
  "code": 0,
  "catalog": {
    "name": "hive_prod",
    "type": "RELATIONAL",
    "provider": "hive",
    "comment": "Production Hive catalog",
    "properties": {
      "metastore.uris": "thrift://localhost:9083"
    },
    "audit": {
      "creator": "user1",
      "createTime": "2025-11-10T10:00:00Z"
    }
  }
}

List Schema #

List all Schemas (databases) under the specified Catalog.

• Method: GET
• Path: /api/metalakes/{metalake_name}/catalogs/{catalog_name}/schemas

Request example:

curl -X GET 'https://{endpoint}/api/metalakes/your_account_id/catalogs/hive_prod/schemas' \
--header 'X-Date: 20251117T091500Z' \
--header 'Authorization: HMAC-SHA256 Credential={ak}/20251117/{region}/gravitino/request, SignedHeaders=host;x-date, Signature={signature}'

Response example:

{
  "code": 0,
  "identifiers": [
    {
      "namespace": [
        "your_account_id",
        "hive_prod"
      ],
      "name": "default"
    },
    {
      "namespace": [
        "your_account_id",
        "hive_prod"
      ],
      "name": "sales_db"
    }
  ]
}

List Table #

List all Tables under the specified Schema.

• Method: GET
• Path: /api/metalakes/{metalake_name}/catalogs/{catalog_name}/schemas/{schema_name}/tables

Request example:

curl -X GET 'https://{endpoint}/api/metalakes/your_account_id/catalogs/hive_prod/schemas/sales_db/tables' \
--header 'X-Date: 20251117T092000Z' \
--header 'Authorization: HMAC-SHA256 Credential={ak}/20251117/{region}/gravitino/request, SignedHeaders=host;x-date, Signature={signature}'

Response example:

{
  "code": 0,
  "identifiers": [
    {
      "namespace": [
        "your_account_id",
        "hive_prod",
        "sales_db"
      ],
      "name": "orders"
    },
    {
      "namespace": [
        "your_account_id",
        "hive_prod",
        "sales_db"
      ],
      "name": "customers"
    }
  ]
}

Fileset, Model, Topic #

Currently, the product only supports Hive Catalog. To use other types of Catalogs, please contact technical support.

Pagination parameter description #

For APIs that return lists (such as listing Catalogs, Schemas, and Tables), pagination parameters are supported to control the number and position of returned results.

• pageSize: Specifies the number of entries returned per page. The default is 100.
• pageToken: Token used to obtain the next page of results. No need to provide this parameter for the first request. For subsequent requests, use the value of nextPageToken returned in the previous response as this parameter.

Region example values #

When making API requests, you must specify the correct Region in the scope of the signature credentials and/or the request header. The following are example values for some available zones in Volcano Engine. Please refer to the region where the service is located for specifics:

• cn-beijing
• cn-shanghai (to be released)
• cn-guangzhou (to be released)

Common issues and troubleshooting #

Q: When calling the API, 401 Unauthorized or SignatureDoesNotMatch error is returned. What is the cause?
A: This usually indicates an error in the API request signature. Please check the following carefully:

1. Whether the AK/SK is correct and has not expired.
2. Whether the time in the X-Date request header matches the server's current UTC time, with a deviation not exceeding 15 minutes.
3. Whether the HTTP request content involved in the signature (method, path, parameters, request headers) matches what was actually sent.
4. Whether the signature calculation process strictly follows the specifications in the official Volcano Engine documentation.

Q: How can you confirm which metalake_name should be used?
A: metalake_name is always mapped to the Volcano Engine account ID. You can find it on the account management page in the Volcano Engine console.
Q: What should be entered in the provider field when creating a Catalog?
A: provider specifies the type of Catalog, such as hive, iceberg, jdbc, and so on. In the Volcano Engine managed environment, you should usually enter hive to connect to the Hive Catalog in LAS.