Skip to content

OpenAPI specs: update README with detailed API specifications #3629

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
adutra merged 1 commit into from
Feb 3, 2026
Merged

OpenAPI specs: update README with detailed API specifications #3629

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 28 additions & 8 deletions spec/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,14 +17,34 @@
under the License.
-->

# Polaris API Specifications

Polaris provides two sets of OpenAPI specifications:
- `polaris-management-service.yml` - Defines the management APIs for using Polaris to create and manage Iceberg catalogs and their principals
- `polaris-catalog-service.yaml` - Defines the specification for the Polaris Catalog API, which encompasses both the Iceberg REST Catalog API
and Polaris-native API.
- `polaris-catalog-apis` - Contains the specification for Polaris-specific Catalog APIs
- `iceberg-rest-catalog-open-api.yaml` - Contains the specification for Iceberg Rest Catalog API
# Apache Polaris API Specifications

Apache Polaris provides the following OpenAPI specifications:

- [polaris-management-service.yml](polaris-management-service.yml) - Defines the management APIs for creating and managing
principals, principal roles, catalogs and catalog roles.

- [polaris-catalog-service.yaml](polaris-catalog-service.yaml) - Defines the specification for the Apache Polaris
Catalog API, which encompasses both the Apache Iceberg REST Catalog API and Apache
Polaris-native APIs:

- [iceberg-rest-catalog-open-api.yaml](iceberg-rest-catalog-open-api.yaml) - Contains the specification for
Apache Iceberg Rest Catalog API.

- [polaris-catalog-apis](polaris-catalog-apis) - This folder contains the specifications for Apache
Polaris-specific Catalog APIs:

- [generic-tables-api.yaml](polaris-catalog-apis/generic-tables-api.yaml) - Contains the specification for
the Generic Tables API.

- [notifications-api.yaml](polaris-catalog-apis/notifications-api.yaml) - Contains the specification for
the Notifications API.

- [policy-apis.yaml](polaris-catalog-apis/policy-apis.yaml) - Contains the specification for the Policy APIs.

- [oauth-tokens-api.yaml](polaris-catalog-apis/oauth-tokens-api.yaml) - Contains the specification for the
internal OAuth Token endpoint, extracted from the Apache Iceberg REST Catalog API.


## Generated Specification Files
The specification files in the generated folder are automatically created using OpenAPI bundling tools such as
Expand Down